OpenParable
Skip to content
← Back to skills

Higress Openclaw Integration

Apps & Automation
higress-openclaw-integration

Higress Openclaw Integration is an Agent Skill for apps & automation published in the higress-group/higress repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Deploy and configure Higress AI Gateway for OpenClaw integration. Use when: (1) User wants to deploy Higress AI Gateway, (2) User wants to configure OpenClaw to use more model providers, (3) User mentions 'higress', 'ai gateway', 'model gateway', 'AI网关', (4) User wants to set up model routing or auto-routing, (5) User needs to manage LLM provider API keys.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/higress-group/higress/blob/HEAD/.claude/skills/higress-openclaw-integration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/higress-openclaw-integration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Higress AI Gateway Integration

Deploy Higress AI Gateway and configure OpenClaw to use it as a unified model provider.

Quick Start

Step 1: Collect Information from User

Ask the user for the following information upfront:

  1. Which LLM provider(s) to use? (at least one required)

    Commonly Used Providers:

    ProviderParameterNotes
    智谱 / z.ai--zhipuai-keyModels: glm-*, Code Plan mode enabled by default
    Claude Code--claude-code-keyRequires OAuth token from claude setup-token
    Moonshot (Kimi)--moonshot-keyModels: moonshot-, kimi-
    Minimax--minimax-keyModels: abab-*
    阿里云通义千问 (Dashscope)--dashscope-keyModels: qwen*
    OpenAI--openai-keyModels: gpt-, o1-, o3-*
    DeepSeek--deepseek-keyModels: deepseep-*
    Grok--grok-keyModels: grok-*

    Other Providers:

    ProviderParameterNotes
    Claude--claude-keyModels: claude-*
    Google Gemini--gemini-keyModels: gemini-*
    OpenRouter--openrouter-keySupports all models (catch-all)
    Groq--groq-keyFast inference
    Doubao (豆包)--doubao-keyModels: doubao-*
    Mistral--mistral-keyModels: mistral-*
    Baichuan (百川)--baichuan-keyModels: Baichuan*
    01.AI (Yi)--yi-keyModels: yi-*
    Stepfun (阶跃星辰)--stepfun-keyModels: step-*
    Cohere--cohere-keyModels: command*
    Fireworks AI--fireworks-key-
    Together AI--togetherai-key-
    GitHub Models--github-key-

    Cloud Providers (require additional config):

    • Azure OpenAI: --azure-key (requires service URL)
    • AWS Bedrock: --bedrock-key (requires region and access key)
    • Google Vertex AI: --vertex-key (requires project ID and region)

    Brand Name Display (z.ai / 智谱):

    • If user communicates in Chinese: display as "智谱"
    • If user communicates in English: display as "z.ai"
  2. Enable auto-routing? (recommended)

    • If yes: --auto-routing --auto-routing-default-model <model-name>
    • Auto-routing allows using model="higress/auto" to automatically route requests based on message content
  3. Custom ports? (optional, defaults: HTTP=8080, HTTPS=8443, Console=8001)

Step 2: Deploy Gateway

Auto-detect region for z.ai / 智谱 domain configuration:

When user selects z.ai / 智谱 provider, detect their region:

# Run region detection script (scripts/detect-region.sh relative to skill directory)
REGION=$(bash scripts/detect-region.sh)
# Output: "china" or "international"

Based on detection result:

  • If REGION="china": use default domain open.bigmodel.cn, no extra parameter needed
  • If REGION="international": automatically add --zhipuai-domain api.z.ai to deployment command

After deployment (for international users): Notify user in English: "The z.ai endpoint domain has been set to api.z.ai. If you want to change it, let me know and I can update the configuration."

# Create installation directory
mkdir -p higress-install
cd higress-install

# Download script (if not exists)
curl -fsSL https://higress.ai/ai-gateway/install.sh -o get-ai-gateway.sh
chmod +x get-ai-gateway.sh

# Deploy with user's configuration
# For z.ai / 智谱: always include --zhipuai-code-plan-mode
# For non-China users: include --zhipuai-domain api.z.ai
./get-ai-gateway.sh start --non-interactive \
  --<provider>-key <api-key> \
  [--auto-routing --auto-routing-default-model <model>]

z.ai / 智谱 Options:

OptionDescription
--zhipuai-code-plan-modeEnable Code Plan mode (enabled by default)
--zhipuai-domain <domain>Custom domain, default: open.bigmodel.cn (China), api.z.ai (international)

Example (China user):

./get-ai-gateway.sh start --non-interactive \
  --zhipuai-key sk-xxx \
  --zhipuai-code-plan-mode \
  --auto-routing \
  --auto-routing-default-model glm-5

Example (International user):

./get-ai-gateway.sh start --non-interactive \
  --zhipuai-key sk-xxx \
  --zhipuai-domain api.z.ai \
  --zhipuai-code-plan-mode \
  --auto-routing \
  --auto-routing-default-model glm-5

Step 3: Install OpenClaw Plugin

Install the Higress provider plugin for OpenClaw:

# Copy plugin files (PLUGIN_SRC is relative to skill directory: scripts/plugin)
PLUGIN_SRC="scripts/plugin"
PLUGIN_DEST="$HOME/.openclaw/extensions/higress"

mkdir -p "$PLUGIN_DEST"
cp -r "$PLUGIN_SRC"/* "$PLUGIN_DEST/"

Tell user to run the following commands manually in their terminal (interactive commands, cannot be executed by AI agent):

# Step 1: Enable the plugin
openclaw plugins enable higress

# Step 2: Configure provider (interactive - will prompt for Gateway URL, API Key, models, etc.)
openclaw models auth login --provider higress --set-default

# Step 3: Restart OpenClaw gateway to apply changes
openclaw gateway restart

The openclaw models auth login command will interactively prompt for:

  1. Gateway URL (default: http://localhost:8080)
  2. Console URL (default: http://localhost:8001)
  3. API Key (optional for local deployments)
  4. Model list (auto-detected or manually specified)
  5. Auto-routing default model (if using higress/auto)

After configuration and restart, Higress models are available in OpenClaw with higress/ prefix (e.g., higress/glm-5, higress/auto).

Future Configuration Updates (No Restart Needed)

After the initial setup, you can manage your configuration through conversation with OpenClaw:

  • Add New Providers: Add new LLM providers (e.g., DeepSeek, OpenAI, Claude) and their models dynamically.
  • Update API Keys: Update existing provider API keys without service restart.
  • Configure Auto-routing: If you've set up multiple models, ask OpenClaw to configure auto-routing rules. Requests will be intelligently routed based on your message content, using the most suitable model automatically.

All configuration changes are hot-loaded through Higress — no openclaw gateway restart required. Iterate on your model provider setup dynamically without service interruption!

Post-Deployment Management

Add/Update API Keys (Hot-reload)

./get-ai-gateway.sh config add --provider <provider> --key <api-key>
./get-ai-gateway.sh config list
./get-ai-gateway.sh config remove --provider <provider>

Provider aliases: dashscope/qwen, moonshot/kimi, zhipuai/zhipu

Update z.ai Domain (Hot-reload)

If user wants to change the z.ai domain after deployment:

# Update domain configuration
./get-ai-gateway.sh config add --provider zhipuai --extra-config "zhipuDomain=api.z.ai"
# Or revert to China endpoint
./get-ai-gateway.sh config add --provider zhipuai --extra-config "zhipuDomain=open.bigmodel.cn"

Add Routing Rules (for auto-routing)

# Add rule: route to specific model when message starts with trigger
./get-ai-gateway.sh route add --model <model> --trigger "keyword1|keyword2"

# Examples
./get-ai-gateway.sh route add --model glm-4-flash --trigger "quick|fast"
./get-ai-gateway.sh route add --model claude-opus-4 --trigger "think|complex"
./get-ai-gateway.sh route add --model deepseek-coder --trigger "code|debug"

# List/remove rules
./get-ai-gateway.sh route list
./get-ai-gateway.sh route remove --rule-id 0

Stop/Delete Gateway

./get-ai-gateway.sh stop
./get-ai-gateway.sh delete

Endpoints

EndpointURL
Chat Completionshttp://localhost:8080/v1/chat/completions
Consolehttp://localhost:8001
Logs./higress-install/logs/access.log

Testing

# Test with specific model
curl 'http://localhost:8080/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{"model": "<model-name>", "messages": [{"role": "user", "content": "Hello"}]}'

# Test auto-routing (if enabled)
curl 'http://localhost:8080/v1/chat/completions' \
  -H 'Content-Type: application/json' \
  -d '{"model": "higress/auto", "messages": [{"role": "user", "content": "What is AI?"}]}'

Troubleshooting

IssueSolution
Container fails to startCheck docker logs higress-ai-gateway
Port already in useUse --http-port, --console-port to change ports
API key errorRun ./get-ai-gateway.sh config list to verify keys
Auto-routing not workingEnsure --auto-routing was set during deployment
Slow image downloadScript auto-selects nearest registry based on timezone

Important Notes

  1. Claude Code Mode: Requires OAuth token from claude setup-token command, not a regular API key
  2. z.ai Code Plan Mode: Enabled by default, uses /api/coding/paas/v4/chat/completions endpoint, optimized for coding tasks
  3. z.ai Domain Selection:
    • China users: open.bigmodel.cn (default)
    • International users: api.z.ai (auto-detected based on timezone)
    • Users can update domain anytime after deployment
  4. Auto-routing: Must be enabled during initial deployment (--auto-routing); routing rules can be added later
  5. OpenClaw Integration: The openclaw models auth login and openclaw gateway restart commands are interactive and must be run by the user manually in their terminal
  6. Hot-reload: API key changes take effect immediately; no container restart needed