Hydra / Uandai (packaging + programmatic API)

Bundled docs version: 2026.06.09

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

First-time setup (chat → persist)

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

Parse from the user message (setup-only; do not repeat key in later work prompts):
- HYDRA_API_ORIGIN — API host without /api (e.g. https://api.uandai.ai or http://127.0.0.1:8000)
- HYDRA_API_BASE_URL — API prefix with /api (e.g. https://api.uandai.ai/api)
- HYDRA_API_KEY — full hyd_live_… from hydra-app → Settings → API Keys
Install the full skill folder (SKILL.md + references/) under ~/.openclaw/skills/hydra-uandai/ (preferred) or <workspace>/skills/hydra-uandai/ for local dev.
Merge into ~/.openclaw/openclaw.json under skills.entries["hydra-uandai"]:


{

  skills: {

    entries: {

      "hydra-uandai": {

        enabled: true,

        apiKey: "hyd_live_…",

        env: {

          HYDRA_API_KEY: "hyd_live_…",

          HYDRA_API_BASE_URL: "https://api.uandai.ai/api",

          HYDRA_API_ORIGIN: "https://api.uandai.ai",

        },

      },

    },

  },

}

Do not echo the full API key back. Tell the user to run /new or restart the gateway.
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 Hydra action

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

| Task | Read |

|------|------|

| Package workspace zip | references/agent-packaging.md |

| Exchange, upload, invoke | references/programmatic-api.md |

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

Default prod origin: https://api.uandai.ai

Packaging (OpenClaw workspace → zip)

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

Never zip the live workspace root directly
Staging: copy to output/<agent>-workspace/ with exclusions → validate → zip staging contents only
Output: output/<agent-name>-workspace.zip
Hydra 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/, hydra-uandai/ — max 50MB
Do not include this skill in the upload zip. Install on the trainer machine at ~/.openclaw/skills/hydra-uandai/ (full folder with references/). A copy under <workspace>/skills/hydra-uandai/ is for local dev only — exclude it when packaging.
Report: 📍 Path: MEDIA:<path-to-zip>

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

API authentication (exchange required)

Raw API keys work only on exchange:


POST /v1/auth/token

Authorization: Bearer $HYDRA_API_KEY

Alternative on exchange only: X-Hydra-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 $HYDRA_API_KEY on upload, invoke, or list endpoints.

Workflows

Trainer — publish end-to-end: setup (if needed) → read references/agent-packaging.md → package zip → read references/programmatic-api.md → exchange → POST /v1/agents/upload → return agent.id and agent.revision_no → optional POST /agents/{id}/proposals

Trainer — upload only: exchange → POST /v1/agents/upload with multipart: bundle (zip) + agent_name + description + subscription_price + default_model_identifier + provider config_data_type_json / test_values_json (see references/programmatic-api.md; Ollama needs OLLAMA_KEY + OLLAMA_URL)

Subscriber — discover: exchange → GET /v1/me/subscriptions → GET /v1/me/activations?invokable_only=true

Subscriber — invoke: exchange → POST /v1/executions → poll GET /v1/executions/{run_id} until terminal

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)