Higress Openclaw Integration

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:

Other Providers:

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:

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

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

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

Higress AI Gateway - Troubleshooting

Common issues and solutions for Higress AI Gateway deployment and operation.

Container Issues

Container fails to start

Check Docker is running:

docker info

Check port availability:

netstat -tlnp | grep 8080

View container logs:

docker logs higress-ai-gateway

Gateway not responding

Check container status:

docker ps -a

Verify port mapping:

docker port higress-ai-gateway

Test locally:

curl http://localhost:8080/v1/models

File System Issues

"too many open files" error from API server

Symptom:

panic: unable to create REST storage for a resource due to too many open files, will die

or

command failed err="failed to create shared file watcher: too many open files"

Root Cause:

The system's fs.inotify.max_user_instances limit is too low. This commonly occurs on systems with many Docker containers, as each container can consume inotify instances.

Check current limit:

cat /proc/sys/fs/inotify/max_user_instances

Default is often 128, which is insufficient when running multiple containers.

Solution:

Increase the inotify instance limit to 8192:

# Temporarily (until next reboot)
sudo sysctl -w fs.inotify.max_user_instances=8192

# Permanently (survives reboots)
echo "fs.inotify.max_user_instances = 8192" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Verify:

cat /proc/sys/fs/inotify/max_user_instances
# Should output: 8192

Restart the container:

docker restart higress-ai-gateway

Additional inotify tunables (if still experiencing issues):

# Increase max watches per user
sudo sysctl -w fs.inotify.max_user_watches=524288

# Increase max queued events
sudo sysctl -w fs.inotify.max_queued_events=32768

To make these permanent as well:

echo "fs.inotify.max_user_watches = 524288" | sudo tee -a /etc/sysctl.conf
echo "fs.inotify.max_queued_events = 32768" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Plugin Issues

Plugin not recognized

Verify plugin installation:

For Clawdbot:

ls -la ~/.clawdbot/extensions/higress-ai-gateway

For OpenClaw:

ls -la ~/.openclaw/extensions/higress-ai-gateway

Check package.json:

Ensure package.json contains the correct extension field:

• Clawdbot: "clawdbot.extensions"
• OpenClaw: "openclaw.extensions"

Restart the runtime:

# Restart Clawdbot gateway
clawdbot gateway restart

# Or OpenClaw gateway
openclaw gateway restart

Routing Issues

Auto-routing not working

Confirm model is in list:

# Check if higress/auto is available
clawdbot models list | grep "higress/auto"

Check routing rules exist:

./get-ai-gateway.sh route list

Verify default model is configured:

./get-ai-gateway.sh config list

Check gateway logs:

docker logs higress-ai-gateway | grep -i routing

View access logs:

tail -f ./higress/logs/access.log

Configuration Issues

Timezone detection fails

Manually check timezone:

timedatectl show --property=Timezone --value

Or check timezone file:

cat /etc/timezone

Fallback behavior:

• If detection fails, defaults to Hangzhou mirror
• Manual override: Set IMAGE_REPO environment variable

Manual repository selection:

# For China/Asia
IMAGE_REPO="higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/all-in-one"

# For Southeast Asia
IMAGE_REPO="higress-registry.ap-southeast-7.cr.aliyuncs.com/higress/all-in-one"

# For North America
IMAGE_REPO="higress-registry.us-west-1.cr.aliyuncs.com/higress/all-in-one"

# Use in deployment
IMAGE_REPO="$IMAGE_REPO" ./get-ai-gateway.sh start --non-interactive ...

Performance Issues

Slow image downloads

Check selected repository:

echo $IMAGE_REPO

Manually select closest mirror:

See Configuration Issues → Timezone detection fails for manual repository selection.

High memory usage

Check container stats:

docker stats higress-ai-gateway

View resource limits:

docker inspect higress-ai-gateway | grep -A 10 "HostConfig"

Set memory limits:

# Stop container
./get-ai-gateway.sh stop

# Manually restart with limits
docker run -d \
  --name higress-ai-gateway \
  --memory="4g" \
  --memory-swap="4g" \
  ...

Log Analysis

Access logs location

# Default location
./higress/logs/access.log

# View real-time logs
tail -f ./higress/logs/access.log

Container logs

# View all logs
docker logs higress-ai-gateway

# Follow logs
docker logs -f higress-ai-gateway

# Last 100 lines
docker logs --tail 100 higress-ai-gateway

# With timestamps
docker logs -t higress-ai-gateway

Network Issues

Cannot connect to gateway

Verify container is running:

docker ps | grep higress-ai-gateway

Check port bindings:

docker port higress-ai-gateway

Test from inside container:

docker exec higress-ai-gateway curl localhost:8080/v1/models

Check firewall rules:

# Check if port is accessible
sudo ufw status | grep 8080

# Allow port (if needed)
sudo ufw allow 8080/tcp

DNS resolution issues

Test from container:

docker exec higress-ai-gateway ping -c 3 api.openai.com

Check DNS settings:

docker exec higress-ai-gateway cat /etc/resolv.conf

Getting Help

If you're still experiencing issues:

1. Collect logs:

   docker logs higress-ai-gateway > gateway.log 2>&1
   cat ./higress/logs/access.log > access.log

2. Check system info:

   docker version
   docker info
   uname -a
   cat /proc/sys/fs/inotify/max_user_instances

3. Report issue:

• Repository: https://github.com/higress-group/higress-standalone
• Include: logs, system info, deployment command used

Higress AI Gateway Plugin

OpenClaw model provider plugin for Higress AI Gateway with auto-routing support.

What is this?

This is a TypeScript-based provider plugin that enables OpenClaw to use Higress AI Gateway as a model provider. It provides:

• Auto-routing support: Use higress/auto to intelligently route requests based on message content
• Dynamic model discovery: Auto-detect available models from Higress Console
• Smart URL handling: Automatic URL normalization and validation
• Flexible authentication: Support for both local and remote gateway deployments

Files

• index.ts: Main plugin implementation
• package.json: NPM package metadata and OpenClaw extension declaration
• openclaw.plugin.json: Plugin manifest for OpenClaw

Installation

This plugin is automatically installed when you use the higress-openclaw-integration skill. See parent SKILL.md for complete installation instructions.

Manual Installation

If you need to install manually:

# Copy plugin files
mkdir -p "$HOME/.openclaw/extensions/higress"
cp -r ./* "$HOME/.openclaw/extensions/higress/"

# Configure provider
openclaw plugins enable higress
openclaw models auth login --provider higress

Usage

After installation, configure Higress as a model provider:

openclaw models auth login --provider higress

The plugin will 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)

Related Resources

• Parent Skill: higress-openclaw-integration
• Auto-routing Configuration: higress-auto-router

License

Apache-2.0