Higress Gateway Management

Manage the Higress AI Gateway via its Console API (consumers, routes, AI providers, MCP servers). Use when creating consumers, configuring routes, or managin...

Security Scan

The skill's runtime instructions are coherent with managing a local Higress Console, but it expects sensitive environment variables and a session cookie file that are not declared in the skill metadata — this mismatch is concerning and should be clarified before installing.

Purpose & Capability

The SKILL.md describes managing the Higress Console API (consumers, AI routes, providers, etc.), and the included OpenAPI reference aligns with that purpose. However, the skill metadata declares no required environment variables or primary credential while the instructions clearly rely on HICLAW_ADMIN_USER, HICLAW_ADMIN_PASSWORD, HICLAW_AI_GATEWAY_DOMAIN, and HIGRESS_COOKIE_FILE — an inconsistency between claimed requirements and actual runtime needs.

Instruction Scope

The instructions direct the agent to post and get against a local Console API (http://127.0.0.1:8001), use a session cookie file, and read admin credentials from environment variables. Those actions are expected for a gateway management skill, but the SKILL.md gives the agent access to sensitive artifacts (admin password and session cookie) and uses shell commands (curl, openssl, jq) without limiting what context the agent may read — the guidance to read a cookie file and env vars expands scope to sensitive local state.

Install Mechanism

There is no install spec and no code files to execute; the skill is instruction-only. This minimizes supply-chain risk since nothing is downloaded or written by the skill bundle itself.

Credentials

The SKILL.md explicitly depends on admin credentials and a session cookie file (sensitive secrets) but the skill manifest declares no required env vars or primary credential. Requesting admin-level credentials for gateway management is plausible, but the manifest should declare those env vars and the primary credential so users know what will be accessed. The mismatch means the skill would access sensitive secrets without being upfront in its metadata.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It does not include an installer that modifies other skills or system-wide settings; no persistent elevated privilege is requested by the bundle itself.

What to consider before installing

This skill appears to be a legitimate helper for a local Higress Console, but it relies on sensitive environment variables and a session cookie (HICLAW_ADMIN_USER, HICLAW_ADMIN_PASSWORD, HICLAW_AI_GATEWAY_DOMAIN, HIGRESS_COOKIE_FILE) even though the registry metadata lists none. Before installing: (1) confirm the skill source/trustworthiness (homepage/source unknown), (2) verify those environment variables are intentionally present in the runtime container and you are comfortable granting the skill access to the admin account and cookie file, (3) ask the publisher to update the metadata to declare required env vars and the primary credential, and (4) consider running the curl commands manually or in a controlled environment first rather than granting autonomous agent invocation until metadata and trust are clarified.

Higress AI Gateway Management

Overview

This skill allows you to manage the Higress AI Gateway via its Console API. The Console API runs at http://127.0.0.1:8001 and uses Session Cookie authentication (NOT Basic Auth).

Environment Variables

These environment variables are pre-configured in the Manager container. Access them directly in bash:

# Core configuration (set by hiclaw-install.sh)
HICLAW_ADMIN_USER      # Admin username for Higress Console
HICLAW_ADMIN_PASSWORD  # Admin password for Higress Console
HICLAW_AI_GATEWAY_DOMAIN  # AI Gateway domain (e.g., aigw-local.hiclaw.io)
HIGRESS_COOKIE_FILE    # Path to session cookie file

No need to set defaults - these are always available in the container environment.

Authentication

A session cookie file is stored at the path in ${HIGRESS_COOKIE_FILE} environment variable. Use it with curl -b "${HIGRESS_COOKIE_FILE}".

If the cookie expires, re-login:

curl -X POST http://127.0.0.1:8001/session/login \
  -H 'Content-Type: application/json' \
  -c "${HIGRESS_COOKIE_FILE}" \
  -d '{"name": "'"${HICLAW_ADMIN_USER}"'", "password": "'"${HICLAW_ADMIN_PASSWORD}"'"}'

Consumer Management

List Consumers

curl -s http://127.0.0.1:8001/v1/consumers -b "${HIGRESS_COOKIE_FILE}" | jq

Create Consumer

curl -X POST http://127.0.0.1:8001/v1/consumers \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "worker-alice",
    "credentials": [{
      "type": "key-auth",
      "source": "BEARER",
      "values": ["<GENERATED_KEY>"]
    }]
  }'

Update Consumer (e.g., replace credential key)

# GET-modify-PUT pattern (consumers do NOT have a version field)
NEW_KEY=$(openssl rand -hex 32)
CONSUMER=$(curl -s http://127.0.0.1:8001/v1/consumers/worker-alice -b "${HIGRESS_COOKIE_FILE}")
UPDATED=$(echo $CONSUMER | jq --arg new "$NEW_KEY" '.credentials[0].values = [$new]')
curl -X PUT http://127.0.0.1:8001/v1/consumers/worker-alice \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d "$UPDATED"

Delete Consumer

curl -X DELETE http://127.0.0.1:8001/v1/consumers/worker-alice -b "${HIGRESS_COOKIE_FILE}"

AI Route Management

AI routes are internal routes managed via a separate API at /v1/ai/routes. They define LLM provider routing with model-level predicates, domain matching, and consumer auth. Do NOT use /v1/routes for AI routes.

List AI Routes

curl -s http://127.0.0.1:8001/v1/ai/routes -b "${HIGRESS_COOKIE_FILE}" | jq

Get AI Route by Name

curl -s http://127.0.0.1:8001/v1/ai/routes/default-ai-route -b "${HIGRESS_COOKIE_FILE}" | jq

Create AI Route

The system initializes with a default-ai-route that has no modelPredicates — all model requests go through it. When the human asks to add a new provider, create a separate AI route with modelPredicates to distinguish which models go where:

# Example: add a DeepSeek route alongside the existing default route
curl -X POST http://127.0.0.1:8001/v1/ai/routes \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "deepseek-route",
    "domains": ["${HICLAW_AI_GATEWAY_DOMAIN}"],
    "pathPredicate": {"matchType": "PRE", "matchValue": "/", "caseSensitive": false},
    "upstreams": [{"provider": "deepseek", "weight": 100, "modelMapping": {}}],
    "modelPredicates": [{"matchType": "PRE", "matchValue": "deepseek"}],
    "authConfig": {
      "enabled": true,
      "allowedCredentialTypes": ["key-auth"],
      "allowedConsumers": ["manager"]
    }
  }'

When adding a new provider route with modelPredicates, also update the default-ai-route to add matching modelPredicates for its own models, so routes are unambiguous.

Key fields:

• domains: which domain(s) this AI route serves (e.g. ${HICLAW_AI_GATEWAY_DOMAIN})
• upstreams: LLM provider(s) with weight and optional model mapping
• modelPredicates: match models by prefix/exact/regex (e.g. {"matchType":"PRE","matchValue":"deepseek"} routes all deepseek* models). Omit when only one route exists
• authConfig: consumer-level access control

Update AI Route (e.g., grant Worker access)

# Step 1: GET current AI route
AI_ROUTE=$(curl -s http://127.0.0.1:8001/v1/ai/routes/default-ai-route -b "${HIGRESS_COOKIE_FILE}")

# Step 2: Add worker-alice to allowedConsumers
UPDATED=$(echo $AI_ROUTE | jq '.authConfig.allowedConsumers += ["worker-alice"]')

# Step 3: PUT full object (AI Route has "version" field, include it)
curl -X PUT http://127.0.0.1:8001/v1/ai/routes/default-ai-route \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d "$UPDATED"

Delete AI Route

curl -X DELETE http://127.0.0.1:8001/v1/ai/routes/<route-name> -b "${HIGRESS_COOKIE_FILE}"

LLM Provider Configuration

List AI Providers

curl -s http://127.0.0.1:8001/v1/ai/providers -b "${HIGRESS_COOKIE_FILE}" | jq

Create Provider

# Qwen (native type)
curl -X POST http://127.0.0.1:8001/v1/ai/providers \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "qwen", "name": "qwen",
    "tokens": ["<API_KEY>"], "protocol": "openai/v1",
    "tokenFailoverConfig": {"enabled": false},
    "rawConfigs": {"qwenEnableSearch": false, "qwenEnableCompatible": true, "qwenFileIds": []}
  }'

# OpenAI-compatible (generic)
curl -X POST http://127.0.0.1:8001/v1/ai/providers \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "openai", "name": "my-provider",
    "tokens": ["<API_KEY>"], "protocol": "openai/v1",
    "modelMapping": {},
    "rawConfigs": {"apiUrl": "https://api.example.com/v1"}
  }'

Update Provider (e.g., rotate API keys)

# GET-modify-PUT pattern (provider has "version" field)
PROVIDER=$(curl -s http://127.0.0.1:8001/v1/ai/providers/qwen -b "${HIGRESS_COOKIE_FILE}")
UPDATED=$(echo $PROVIDER | jq '.tokens = ["<NEW_KEY>"]')
curl -X PUT http://127.0.0.1:8001/v1/ai/providers/qwen \
  -b "${HIGRESS_COOKIE_FILE}" \
  -H 'Content-Type: application/json' \
  -d "$UPDATED"

MCP Server Management

For creating, updating, listing, and deleting MCP Servers, as well as managing consumer access to MCP tools, see the mcp-server-management skill.

Important Notes

• Auth Plugin Activation: First configuration takes ~40s, subsequent changes ~10s
• Version field: AI Routes and Providers have a version field. Always GET before PUT to get the latest version.
• Consumer version: Consumers do NOT have a version field
• MCP Server: See mcp-server-management skill for full details on creating and managing MCP servers

<!-- hiclaw-builtin-end -->