ziniao-assistant

Control Ziniao Browser via the local ZClaw bridge—list/open stores, navigate, read content, click, input, screenshot, run automation. Use only tools in Core...

Security Scan

The skill's instructions mostly match a local browser-bridge controller, but it asks the agent to read/write API keys and config files in the user's home and references env vars/config paths that are not declared in the registry metadata — a mismatch that raises privacy and persistence concerns.

Purpose & Capability

The skill's name/description (control Ziniao Browser via a local ZClaw bridge) matches the runtime instructions to call a localhost bridge endpoint. However the SKILL.md requires reading/writing an API key at ~/.zclaw/config.json and reading env vars (ZCLAW_API_KEY, ZCLAW_BASE_URL, ZINIAO_ZCLAW_BASE_URL) even though the registry metadata lists no required env vars or config paths. The omission of those config paths/env vars in the declared requirements is an incoherence.

Instruction Scope

Instructions explicitly require writing the user-provided API key to a persistent config file and permit reading the same file and environment variables. The skill may also request bridge logs and write downloaded files to Downloads. These actions go beyond ephemeral in-memory operations and involve persistent filesystem changes and potentially sensitive logs/keys.

Install Mechanism

This is an instruction-only skill with no install spec and no code files, so it does not download or install third-party code — lower risk from installation mechanics.

Credentials

Although no env vars are declared in the registry metadata, the SKILL.md instructs the agent to read ZCLAW_API_KEY, ZCLAW_BASE_URL / ZINIAO_ZCLAW_BASE_URL and to persist an API key to ~/.zclaw/config.json. Requiring persistent storage of a secret (the API key) without declaring it is disproportionate and should be explicitly requested in metadata and consented to by the user.

Persistence & Privilege

The skill instructs the agent to create ~/.zclaw and write config.json containing the API key — a persistent change in the user's home directory. While the skill is not 'always: true', persistent write of secrets increases the blast radius if the agent invokes the skill autonomously or if the config file is accessible to other processes.

What to consider before installing

This skill appears to genuinely control a local Ziniao/ZClaw bridge, but it asks the agent to store an API key in ~/.zclaw/config.json and to read environment variables that the registry metadata doesn't declare. Before installing or pasting any API key: (1) Verify the skill publisher/source (there's no homepage or known owner). (2) Don't paste secrets unless you trust the skill — prefer setting ZCLAW_API_KEY yourself in a secure config you control instead of letting the agent write it. (3) Ask the publisher to update the registry metadata to declare required config paths and env vars, and to explain why persisting the key is necessary. (4) If you proceed, limit risk by running the bridge and agent in a restricted environment (isolated user account/container), and review ~/.zclaw/config.json permissions and contents after the skill runs. (5) If you need stronger assurance, request a version of the skill that asks for explicit, per-use consent before writing persistent credentials or that uses an OS-native secret store rather than plaintext files.

Available Capabilities

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

Category	Tool	Description
Store	list_stores	List stores (storeId, storeName, platformName, ip). Call once; no loop.
	resolve_store	Resolve store by storeId or storeName.
	open_store	Open store (by storeId/storeName from list or resolve). Call once.
	close_store	Close store by storeId.
Page	visit_page	Navigate to URL, optional waitUntil/timeout.
	get_page_content	Read page content (text/html/structured).
Interaction	query_elements	Query DOM by selector.
	click_element	Click element by selector, optional waitForNavigation.
	input_text	Type into element; optional clear, submit.
	scroll_page	Scroll page or element.
	take_screenshot	Screenshot (full page or viewport).
Waiting	wait_for_element	Wait for selector.
	wait_for_navigation	Wait for navigation.
Automation	execute_script	Run JavaScript in page.
	run_automation	Multi-step automation (steps array).
	extract_data	Extract metadata / page state; mode=running lists launched stores.
Utilities	prepare_agent	Prepare agent resources.
	download_file	Write content to Downloads (content, filename).
	get_logs	Get bridge logs.

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.