Uandai (packaging + programmatic API)#

Bundled docs version: 2026.06.25

Use this skill for all Uandai automation: first-time setup, workspace packaging, upload, subscriptions, and invocation.

First-time setup (chat → persist)#

When the user sends a configure Uandai message with settings, or env vars are missing:

1. Parse from the user message (setup-only; do not repeat key in later work prompts):

   • UANDAI_API_ORIGIN — API host without /api (e.g. https://api.uandai.ai or http://127.0.0.1:8000)

   • APP_SITE_URL — uandai.ai web app origin (no trailing slash; e.g. https://app.uandai.ai or http://127.0.0.1:8080)

   • UANDAI_API_KEY — full uand_live_… from uandai.ai app → Settings → API Keys

API base URL (derived — do not store separately): {UANDAI_API_ORIGIN}/api (e.g. https://api.uandai.ai/api). Use this prefix for all programmatic paths ( /v1/…).

1. Install the full skill folder ( SKILL.md + references/) under ~/.openclaw/skills/uandai-ai/ (preferred) or <workspace>/skills/uandai-ai/ for local dev.

2. Merge into ~/.openclaw/openclaw.json under skills.entries.uandai-ai:

json5

{
  skills: {
    entries: {
      "uandai-ai": {
        enabled: true,
        apiKey: "uand_live_…",
        env: {
          UANDAI_API_KEY: "uand_live_…",
          UANDAI_API_ORIGIN: "https://api.uandai.ai",
          APP_SITE_URL: "https://app.uandai.ai",
        },
      },
    },
  },
}

1. Do not echo the full API key back. Tell the user to run /new or restart the gateway.

2. Optional smoke test: exchange → GET /v1/auth/me.

Security: Prefer a private OpenClaw session for setup messages that contain the key. After setup, operational prompts need no key and no doc URLs.

Before any Uandai action#

Read bundled reference files in this skill directory first. Do not rely on web_fetch unless the user explicitly pastes a Uandai doc URL in the current message.

TaskReadPackage workspace zipreferences/agent-packaging.mdExchange, upload, delete, invokereferences/programmatic-api.mdGallery screenshots + video (REST)references/programmatic-api.md § Gallery media (proxy POST /media; direct upload when direct_upload_enabled)Subscriber OpenClaw gateway ( /openclaw)references/openclaw-integration.md

Optional live refresh: if the user pastes {UANDAI_API_ORIGIN}/docs/agent-packaging, /docs/programmatic-api, or /docs/openclaw-integration in chat, you may web_fetch that URL and prefer it for that session.

Default prod origins: API https://api.uandai.ai (base {ORIGIN}/api); app https://app.uandai.ai

Required inputs before API calls#

Do not call Uandai business endpoints until all required inputs for that endpoint are known.

SourceExamplesEnv / config (setup once)UANDAI_API_ORIGIN, APP_SITE_URL, UANDAI_API_KEY, exchanged access_token; API base = {UANDAI_API_ORIGIN}/apiUser message (minimal ZIP upload)agent_name, description, packaged zipUser message (full ZIP upload)agent_name, description, subscription_price, default_model_identifier, provider URL test value (when required), custom/skill test rows — not {PROVIDER}_KEYUser message (invoke)configs, confirm agent_id / revision_noPrior API responseagent.id, revision_no from upload 201 body ( { "agent": { "id", "revision_no", … } }); activations list for invoke

If any user-sourced field is missing or ambiguous:

1. Ask the user in one concise message listing only missing fields.
2. Do not call the endpoint with placeholders, defaults, or guesses.
3. Confirm values briefly (never echo secrets).

Per-endpoint prerequisite tables and checklists: references/programmatic-api.md.

Packaging (OpenClaw workspace → zip)#

Stable rules (full steps in references/agent-packaging.md):

1. Never zip the live workspace root directly

2. Staging: copy to output/<agent>-workspace/ with exclusions → validate → zip staging contents only

3. Output: output/<agent-name>-workspace.zip

4. Uandai zip layout:

   • Personality files ( SOUL.md, IDENTITY.md, …) at zip root
   • No extra parent wrapper folder in the archive
   • SKILL.md only at skills/<id>/SKILL.md, workspace/skills/<id>/SKILL.md, or zip root
   • Exclude node_modules/, .env, logs/, memory/, .openclaw/, output/, uandai-ai/ — max 50MB

5. Do not include this skill in the upload zip. Install on the trainer machine at ~/.openclaw/skills/uandai-ai/ (full folder with references/). A copy under <workspace>/skills/uandai-ai/ is for local dev only — exclude it when packaging.

6. Report: 📍 Path: MEDIA:<path-to-zip>

Common failures: personality only under workspace/; nested wrapper folder; misplaced skill/SKILL.md; uandai-ai/ in zip ( openclaw_bundle_platform_skill).

API authentication (exchange required)#

Raw API keys work only on exchange:

http

POST /v1/auth/token
Authorization: Bearer $UANDAI_API_KEY

Alternative on exchange only: send the raw key in header X-Uandai-Api-Key or JSON { "api_key": "…" }.

Response: { "access_token", "refresh_token", "user" } — cache in session memory.

All other calls: Authorization: Bearer <access_token>

On access expiry: POST /v1/auth/refresh. On refresh 401: re-exchange if key still active; else user creates a new key in Settings.

Do not send $UANDAI_API_KEY on upload, invoke, or list endpoints.

After upload (trainer)#

Upload 201 response shape: { "agent": { "id", "revision_no", "name", … } }.

Always return to the user:

1. agent.id — numeric agent id from the response
2. revision_no — current revision from the same response (needed for proposal updates and invoke)
3. Manage link — {APP_SITE_URL}/training-center/agents/manage/{agent.id} where they set subscription price, invokable duration, provider LLM URL (when required), default model, and remaining marketplace fields (subscribers supply provider API keys at subscribe/invoke)

Use APP_SITE_URL from skill env (setup above). Do not guess the app origin.

Workflows#

Trainer — publish end-to-end (minimal ZIP): setup → read references/agent-packaging.md → package zip → collect agent_name + description from user → exchange → POST {UANDAI_API_ORIGIN}/api/v1/agents/upload with bundle → return agent.id and revision_no from the upload response → share manage link {APP_SITE_URL}/training-center/agents/manage/{agent.id} (pricing, duration, provider LLM, model, invocation settings) → user completes there or via POST /agents/{id}/proposals → PATCH …/proposals/{id} status=submitted when ready

Trainer — full ZIP upload: collect all ZIP prerequisites from user → optional GET /agents/duration-pricing when invokable → exchange → POST /v1/agents/upload with bundle + agent_name + description + subscription_price + default_model_identifier + provider config_data_type_json / test_values_json (Ollama: OLLAMA_URL only — never OLLAMA_KEY; prefer agent_duration_pricing_id over invokable_duration_seconds when invokable) → return agent.id, revision_no, and the same manage link

Trainer — minimal ZIP only: collect agent_name + description + packaged zip → exchange → POST /v1/agents/upload with bundle — do not block on price/model at upload time; do not use multipart files for the minimal path

Trainer — list / delete agent: optional GET /agents/created (includes can_delete + delete_blockers) or GET /agents/{agent_id}/delete-eligibility → confirm agent_id with user → DELETE /agents/{agent_id} → on 200 confirm { "agent_id", "deleted": true }; on 409 explain the structured code (e.g. agent_delete_entitled_subscribers + destroys_at) — do not retry without resolving it

Subscriber — discover: exchange → GET /v1/me/subscriptions → GET /v1/me/activations?invokable_only=true (or invokable_only=false to include archived agent_removed history)

Subscriber — invoke: exchange → GET /v1/me/activations?invokable_only=true → skip rows with agent_removed: true or is_invokable: false → collect configs from user (and confirm numeric agent_id / revision_no) → POST /v1/executions → poll GET /v1/executions/{run_id} until terminal ( status may start as queued or pending_payment)

Subscriber — archived agent: if agent_removed: true, do not invoke or PATCH configs ( 410 on configs); run history remains via GET /v1/executions?user_agent_id={user_agent_id}

Safety#

• Never log or echo the full API key
• On 401: refresh → re-exchange → key may be revoked
• On 402: user needs credits
• API keys cannot create/revoke other keys (Settings / password JWT only)