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:

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

Commonly Used Providers:

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

Other Providers:

Provider	Parameter	Notes
Claude	`--claude-key`	Models: claude-*
Google Gemini	`--gemini-key`	Models: gemini-*
OpenRouter	`--openrouter-key`	Supports all models (catch-all)
Groq	`--groq-key`	Fast inference
Doubao (豆包)	`--doubao-key`	Models: doubao-*
Mistral	`--mistral-key`	Models: mistral-*
Baichuan (百川)	`--baichuan-key`	Models: Baichuan*
01.AI (Yi)	`--yi-key`	Models: yi-*
Stepfun (阶跃星辰)	`--stepfun-key`	Models: step-*
Cohere	`--cohere-key`	Models: 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"

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
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:

Option	Description
`--zhipuai-code-plan-mode`	Enable 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:

Gateway URL (default: http://localhost:8080)
Console URL (default: http://localhost:8001)
API Key (optional for local deployments)
Model list (auto-detected or manually specified)
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

Endpoint	URL
Chat Completions	http://localhost:8080/v1/chat/completions
Console	http://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

Issue	Solution
Container fails to start	Check `docker logs higress-ai-gateway`
Port already in use	Use `--http-port`, `--console-port` to change ports
API key error	Run `./get-ai-gateway.sh config list` to verify keys
Auto-routing not working	Ensure `--auto-routing` was set during deployment
Slow image download	Script auto-selects nearest registry based on timezone

Important Notes

Claude Code Mode: Requires OAuth token from claude setup-token command, not a regular API key
z.ai Code Plan Mode: Enabled by default, uses /api/coding/paas/v4/chat/completions endpoint, optimized for coding tasks
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
Auto-routing: Must be enabled during initial deployment (--auto-routing); routing rules can be added later
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
Hot-reload: API key changes take effect immediately; no container restart needed

higress-openclaw-integration