Ziniao Assistant

Available Capabilities

All operations go through POST {baseUrl}/zclaw/tools/invoke with tool + args. Only the following tools are valid.

Do not use: run_script → use execute_script; screenshot / get_screenshot → use take_screenshot; execute_automation → use run_automation.

API: How to Invoke Tools (Required)

All tools are invoked through one endpoint only. Do not call other paths.

• Method and path: POST {baseUrl}/zclaw/tools/invoke (e.g. POST http://127.0.0.1:9481/zclaw/tools/invoke). Base URL from ZCLAW_BASE_URL or ZINIAO_ZCLAW_BASE_URL (default http://127.0.0.1:9481).
• Request body (JSON): { "tool": "<name>", "args": { ... } }. Optional: "action": "json".
• tool must be exactly one of the tool names in the Core Tools list below (e.g. list_stores, visit_page, get_page_content, click_element, take_screenshot, execute_script, run_automation). Wrong names (e.g. run_script, screenshot) or custom paths will fail.
• Do not call paths like /zclaw/page/execute, /zclaw/page/visit, /zclaw/page/click, etc. Every tool call must be POST /zclaw/tools/invoke with the correct tool name in the body.

When To Use

Use when the user wants to operate Ziniao Browser or configure the Ziniao–ZClaw bridge (list stores, open store, visit pages, read content, click, input, screenshot, export, automation). When a task has multiple similar sub-items (e.g. several order types or reports), visit or check each one separately before concluding; do not infer from a subset.

Stop on Blocker (Mandatory — Enforced First)

Trigger: Any of: (a) POST {baseUrl}/zclaw/tools/invoke fails with connection refused, timeout, or no response; (b) a required tool call returns an error that makes the task impossible; (c) a required resource (e.g. store not found, API key missing) is missing.

You MUST:

1. Stop immediately. Do not retry the same request. Do not read more code, grep, or open other files to "diagnose" or "work around". Do not design or write "run these steps when the bridge is up" or any follow-up plan.
2. End the turn. Do not speculate on other causes, suggest code changes, or continue the task. Connection or tool failure means the task is not executable—stop only. (User-facing messages for unreachable bridge are handled by the software.)

Hard Constraints

• Stop on blocker: If the bridge is unreachable or a required tool call fails, stop and end the turn; do not retry, read code, or create templates or follow-up plans. See "Stop on Blocker" above.
• No script files: Do not create or run any scripts (.sh/.js/.py or other code files) to execute tasks; use only the tools in Core Tools via POST /zclaw/tools/invoke. Temporary files are allowed (e.g. intermediate data, content for download_file); script/executable files are not.
• All browser actions must stay inside Ziniao Browser or a Ziniao store exposed by the bridge. Do not open system browser, Chrome, Safari, Edge, Firefox, or use Playwright/Puppeteer/browser-use when the bridge fails.
• Use only the tools in Core Tools. Do NOT use: run_script (use execute_script), screenshot or get_screenshot (use take_screenshot), execute_automation (use run_automation), or any tool not listed there.
• Prefer tool-based flow: open store → visit_page → get_page_content / query_elements / click_element / input_text / take_screenshot / download_file / run_automation. Use execute_script only for in-page JavaScript (e.g. DOM extraction), not for orchestration.

API Key: Configure via Conversation (Preferred)

The user can configure the API key by sending it in the conversation. When the user provides an API key (e.g. pastes it, or says “设置 API key 为 xxx”, “my API key is znoc_xxx”, “configure ZCLAW_API_KEY: xxx”), you MUST:

1. Write the key to the config file the skill reads from:
   • macOS / Linux: ~/.zclaw/config.json
   • Windows: %USERPROFILE%\.zclaw\config.json (e.g. C:\Users\<YourName>\.zclaw\config.json) Create the .zclaw directory if it does not exist. File content: JSON with at least "ZCLAW_API_KEY": "<the key the user provided>". If the file already exists, merge: update ZCLAW_API_KEY and keep other keys (e.g. ZCLAW_BASE_URL) unchanged.
2. Immediately use this new API key for all subsequent POST /zclaw/tools/invoke requests in this conversation. Do not wait for a reload; treat the key you just wrote as the current key. If the user provides a new key again later, write again and switch to the new key for the rest of the conversation.

Writing the config file is allowed for API key setup only (creating/updating ~/.zclaw/config.json). Do not create or run scripts; use normal file write to that path.

API Key: Read into Context (Required)

When this skill is used, load the API key into the conversation context so every request (including the first) can authenticate. Use this order (Ziniao and ZClaw both use ZCLAW_API_KEY):

1. User just provided in this conversation — if you have just written the key to the config per “API Key: Configure via Conversation”, use that key for all requests.
2. Environment variable ZCLAW_API_KEY — use if set.
3. Config file ~/.zclaw/config.json — if the key is not in env and not set in conversation, read ZCLAW_API_KEY from this JSON file (e.g. { "ZCLAW_API_KEY": "your-key" }).

Use the resolved key for all POST /zclaw/tools/invoke requests (e.g. header X-ZClaw-Api-Key or body apiKey). Optionally ZCLAW_BASE_URL or ZINIAO_ZCLAW_BASE_URL (default http://127.0.0.1:9481).

Do this at skill load or at the start of the conversation so the key is available and the first tool call does not fail with "Missing bearer token". After the user configures a new key via conversation, update to the new key immediately for the rest of the turn.

Environment & Setup

• API key: Env ZCLAW_API_KEY, or ZCLAW_API_KEY in ~/.zclaw/config.json (see path note below). The bridge also accepts the key via header X-ZClaw-Api-Key or body apiKey.
• Base URL: ZCLAW_BASE_URL or ZINIAO_ZCLAW_BASE_URL (default http://127.0.0.1:9481).
• First time / Rotate key: Obtain a ZClaw API key from your server or Ziniao Ecosystem Center (there is no API key generation in the app settings). You can (1) configure via conversation — tell the assistant your API key and it will write it to ~/.zclaw/config.json and use it immediately; or (2) set ZCLAW_API_KEY in your environment or in ~/.zclaw/config.json; or (3) run bash ziniao-skills/install-ziniao-openclaw-skill.sh "YOUR_API_KEY" (Windows: use install-ziniao-openclaw-skill.ps1 with -ApiKey). After configuring via conversation, the assistant uses the new key for all subsequent requests in that conversation.

Reading the key: The bridge uses process.env.ZCLAW_API_KEY, which works on Windows, macOS, and Linux. The variable must be present in the environment of the process that runs the app (Ziniao/Electron). If the app is started from the GUI (e.g. Dock, Start menu), only system/user environment variables are visible; shell-only exports (e.g. in a terminal) are not. To ensure the key is always available on all platforms, you can use the config file instead of env.

Setting ZCLAW_API_KEY by OS:

• macOS / Linux: (1) Config file (recommended): ~/.zclaw/config.json with { "ZCLAW_API_KEY": "your-key" } (same path on both). (2) Env: In the same shell that starts the app: export ZCLAW_API_KEY=your-key. For GUI launches, add export ZCLAW_API_KEY=... to ~/.bashrc, ~/.zshrc, or ~/.profile, or set it system-wide (e.g. /etc/environment on Linux).
• Windows: (1) Config file (recommended): %USERPROFILE%\.zclaw\config.json (e.g. C:\Users\YourName\.zclaw\config.json) with { "ZCLAW_API_KEY": "your-key" }. (2) Env: System Properties → Environment Variables → add User or System variable ZCLAW_API_KEY; or in PowerShell (current user): [Environment]::SetUserVariable("ZCLAW_API_KEY","your-key"). Restart the app after changing system env.

Invocation: This skill is designed for use with the ZClaw framework (recommended). The Ziniao bridge is an HTTP API; any client that can send requests with a valid API key can call the same tools.

Store Resolution and Opening: Validation and Response Contract

Getting and opening stores follows Ziniao’s existing validation and launch flow: store detail (e.g. default_browser, platform) is fetched via store/detail when launching; the browser is then started using the same logic as the client.

ZClaw responses are filtered by convention and do not expose full Ziniao store details: open_store returns only storeId, name, debugPort, reused, etc.; list_stores returns only storeId, storeName, platformName, ip. ZClaw does not expose full store detail; it only exposes status for stores launched via ZClaw. The running-stores list (e.g. extract_data with mode=running or the running-stores API) contains only storeId, storeName, debugPort, wsUrl.

If open_store or visit_page returns 400 "Store detail not found", the backend store/detail API or its response shape may be failing; the bridge tries several response paths and, when present, includes the server’s msg in the error.

No Extra Scripts (Mandatory)

You must not create or use any scripts to execute tasks. All actions must be performed only through the tools listed in Core Tools. Do not:

• Create or run Node.js, shell, Python, or other script files (e.g. .sh, .js, .py) to accomplish the task.
• Invoke external commands or scripts for steps that the tools can do (list stores, open store, visit page, click, input, screenshot, download_file, run_automation, etc.).

Temporary files are allowed during the run (e.g. temporary data files, intermediate content to pass to download_file, or scratch files). Script files are not allowed — do not create or execute any file intended to be run as code. Use only POST /zclaw/tools/invoke with the tool names and args from Core Tools. If something cannot be done with the existing tools, report the limitation instead of scripting around it.

Store List and Opening (Mandatory)

• No looping: Call list_stores at most once to get data; then call open_store once. Do not repeatedly call list in a cycle.
• To open a store: (1) Get storeId — either from one list_stores (use the item whose storeName matches the user’s store) or from one resolve_store(storeName); (2) Call open_store once with that storeId or with storeName (exact string from the list).
• list_stores response: Each item has exactly: storeId, storeName, platformName, ip. Use storeName when calling resolve_store or open_store (exact match). Do not use other fields as the store name.

Recommended Workflow

1. Store: One list_stores or one resolve_store → get storeId / storeName → one open_store. Match by storeName from list; if ambiguous, ask user or use exact storeId. No fuzzy/substring matching.
2. Page: Before page operations, ensure store is open and call visit_page if needed. Use get_page_content, query_elements, click_element, input_text, take_screenshot, download_file as needed; prefer run_automation for multi-step flows.
3. Errors: Use get_logs on failure; after API key rotation, update config and refresh skills.
4. Multiple similar items: When a task involves multiple similar sub-items (e.g. several order types, several reports), visit or check each item separately before drawing a conclusion; do not infer "all have no data" or "all behave the same" from only a subset.

Core Tools

Only these tools exist. Use exactly these names as the tool field in POST /zclaw/tools/invoke; put parameters in args. Do not use or invent other tool names or other URLs.

Pass one arguments object per call (as args); required keys must be present. When running ZClaw tasks, the bridge operates on the correct tab but does not bring the browser window to the front, so your other windows and work are not interrupted.

Store Management

• list_stores — List stores (call once; no loop). Response: { page, limit, total, items } where each item has storeId, storeName, platformName, ip. Use storeName for resolve/open. Args: page?, limit?, all?, filterKeyword?, storeListType?.
• resolve_store — Resolve by exact storeId or storeName. Args: storeId?, storeName?, expectedName?. Returns storeId and name for open_store.
• open_store — Open store (need storeId from list_stores or resolve_store). Uses store/detail + launch. Returns (filtered): storeId, name, debugPort, reused, and optionally status, windowHandler, launchUrl. Call once. Args: storeId?, storeName? (use list item storeName), expectedName?, launchUrl?, isHeadless?, privacyMode?, windowRatio?.
• close_store — Close store. Args: storeId (required).

Page Navigation & Content

• visit_page — Navigate and wait. Args: storeId, url; optional waitUntil (domcontentloaded|load|networkidle), timeoutMs, targetId.
• get_page_content — Read page content. Args: storeId; optional format (text|html|structured), timeoutMs, targetId.

Page Interaction

• query_elements — DOM by selector. Args: storeId, selector; optional timeoutMs, targetId.
• click_element — Click. Args: storeId, selector; optional waitForNavigation, timeoutMs, targetId.
• input_text — Type into element. Args: storeId, selector, text; optional clear, submit, timeoutMs, targetId.
• scroll_page — Scroll. Args: storeId; optional x, y, selector, behavior (auto|smooth), timeoutMs, targetId.
• take_screenshot — Screenshot (not screenshot). Args: storeId; optional fullPage, path, timeoutMs, targetId.

Page Waiting

• wait_for_element — Wait for selector. Args: storeId, selector; optional timeoutMs, targetId.
• wait_for_navigation — Wait for navigation. Args: storeId; optional timeoutMs, targetId.

Automation & Scripting

• execute_script — Run JS in page (not run_script). Args: storeId, script; optional timeoutMs, targetId.
• run_automation — Multi-step flow. Args: steps (array of { type, ... }).
• extract_data — Extract metadata or page state. Use mode=running to list launched stores (returns only storeId, storeName, debugPort, wsUrl); mode=store returns that store’s launch status only (no store detail). Args: mode? (store|running|plugin|page), storeId?, payload?.

Utilities

• prepare_agent — Prepare agent resources.
• download_file — Write to Downloads. Args: content, filename.
• get_logs — Bridge logs.

Invalid tool names (will fail): run_script, screenshot, get_screenshot, execute_automation — use execute_script and take_screenshot, run_automation instead.