feat: add support for registering custom OpenAI-compatible providers via environment variables

.env.example

@@ -124,6 +124,30 @@ LLM_API_KEY=your_api_key_here
 # Or any other OpenClaw-supported provider (format: provider/model-name)
 LLM_MODEL=anthropic/claude-sonnet-4-5
 
+# Optional: custom OpenAI-compatible provider
+# Only use this if you want to register your own endpoint at startup.
+# Leave all of these empty unless you need a custom provider.
+#
+# Example:
+#   CUSTOM_PROVIDER_NAME=modal
+#   CUSTOM_BASE_URL=https://api.us-west-2.modal.direct/v1
+#   CUSTOM_MODEL_ID=zai-org/GLM-5.1-FP8
+#   LLM_MODEL=modal/zai-org/GLM-5.1-FP8
+#
+# Notes:
+# - CUSTOM_BASE_URL should be the API base URL, not /chat/completions
+# - CUSTOM_PROVIDER_NAME must not reuse a built-in provider name
+# - Uses LLM_API_KEY by default; set CUSTOM_API_KEY only if different
+#
+# CUSTOM_PROVIDER_NAME=modal
+# CUSTOM_BASE_URL=https://your-openai-compatible-endpoint/v1
+# CUSTOM_MODEL_ID=your-model-id
+# CUSTOM_MODEL_NAME=Friendly Model Name
+# CUSTOM_API_KEY=your_custom_api_key_here
+# CUSTOM_API_TYPE=openai-completions
+# CUSTOM_CONTEXT_WINDOW=128000
+# CUSTOM_MAX_TOKENS=500
+
 # [REQUIRED] Gateway authentication token
 # Generate: openssl rand -hex 32
 GATEWAY_TOKEN=your_gateway_token_here

README.md

@@ -219,6 +219,50 @@ LLM_MODEL=provider/model-name
 
 The provider prefix in `LLM_MODEL` tells HuggingClaw how to call it. See [OpenClaw Model Providers](https://docs.openclaw.ai/concepts/model-providers) for the full list.
 
+### Custom OpenAI-Compatible Provider
+
+You can register your own OpenAI-compatible endpoint at startup without touching OpenClaw CLI.
+
+Required env vars:
+
+```bash
+LLM_API_KEY=your_api_key
+LLM_MODEL=modal/zai-org/GLM-5.1-FP8
+CUSTOM_PROVIDER_NAME=modal
+CUSTOM_BASE_URL=https://api.us-west-2.modal.direct/v1
+CUSTOM_MODEL_ID=zai-org/GLM-5.1-FP8
+```
+
+Optional env vars:
+
+```bash
+CUSTOM_MODEL_NAME=GLM-5.1-FP8
+CUSTOM_API_KEY=your_custom_api_key
+CUSTOM_API_TYPE=openai-completions
+CUSTOM_CONTEXT_WINDOW=128000
+CUSTOM_MAX_TOKENS=500
+```
+
+Notes:
+
+- This is for **OpenAI-compatible** endpoints only.
+- `CUSTOM_BASE_URL` should be the API base URL, not `/chat/completions`.
+- `CUSTOM_PROVIDER_NAME` must be a new name and cannot override built-in providers like `openai`, `openrouter`, `google`, or `anthropic`.
+- If `CUSTOM_API_KEY` is not set, HuggingClaw uses `LLM_API_KEY`.
+
+Examples:
+
+- Modal-hosted model:
+  - `CUSTOM_PROVIDER_NAME=modal`
+  - `CUSTOM_BASE_URL=https://api.us-west-2.modal.direct/v1`
+  - `CUSTOM_MODEL_ID=zai-org/GLM-5.1-FP8`
+  - `LLM_MODEL=modal/zai-org/GLM-5.1-FP8`
+- Self-hosted vLLM:
+  - `CUSTOM_PROVIDER_NAME=vllm`
+  - `CUSTOM_BASE_URL=https://your-vllm.example.com/v1`
+  - `CUSTOM_MODEL_ID=Qwen/Qwen2.5-72B-Instruct`
+  - `LLM_MODEL=vllm/Qwen/Qwen2.5-72B-Instruct`
+
 ## 💻 Local Development
 
 ```bash

start.sh

@@ -231,6 +231,73 @@ CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".gateway.auth.token = \"$GATEWAY_TOKEN\"
 # Model configuration at top level
 CONFIG_JSON=$(echo "$CONFIG_JSON" | jq ".agents.defaults.model = \"$LLM_MODEL\"")
 
+# Optional: dynamic custom OpenAI-compatible provider registration
+CUSTOM_PROVIDER_NAME="${CUSTOM_PROVIDER_NAME:-}"
+CUSTOM_BASE_URL="${CUSTOM_BASE_URL:-}"
+CUSTOM_MODEL_ID="${CUSTOM_MODEL_ID:-}"
+CUSTOM_MODEL_NAME="${CUSTOM_MODEL_NAME:-$CUSTOM_MODEL_ID}"
+CUSTOM_API_KEY="${CUSTOM_API_KEY:-$LLM_API_KEY}"
+CUSTOM_API_TYPE="${CUSTOM_API_TYPE:-openai-completions}"
+CUSTOM_CONTEXT_WINDOW="${CUSTOM_CONTEXT_WINDOW:-128000}"
+CUSTOM_MAX_TOKENS="${CUSTOM_MAX_TOKENS:-500}"
+
+if [ -n "$CUSTOM_PROVIDER_NAME" ] || [ -n "$CUSTOM_BASE_URL" ] || [ -n "$CUSTOM_MODEL_ID" ]; then
+  CUSTOM_PROVIDER_NORMALIZED=$(printf '%s' "$CUSTOM_PROVIDER_NAME" | tr '[:upper:]' '[:lower:]')
+  CUSTOM_BASE_URL_NORMALIZED="${CUSTOM_BASE_URL%/}"
+  CUSTOM_PROVIDER_OK=true
+
+  if [ -z "$CUSTOM_PROVIDER_NAME" ] || [ -z "$CUSTOM_BASE_URL" ] || [ -z "$CUSTOM_MODEL_ID" ]; then
+    echo "⚠️  Custom provider skipped: set CUSTOM_PROVIDER_NAME, CUSTOM_BASE_URL, and CUSTOM_MODEL_ID together."
+    CUSTOM_PROVIDER_OK=false
+  fi
+
+  case "$CUSTOM_PROVIDER_NORMALIZED" in
+    anthropic|openai|openai-codex|google|google-vertex|deepseek|opencode|opencode-go|openrouter|kilocode|vercel-ai-gateway|zai|z-ai|z.ai|zhipu|moonshot|kimi-coding|minimax|qwen|modelstudio|xiaomi|volcengine|volcengine-plan|byteplus|byteplus-plan|qianfan|mistral|mistralai|xai|x-ai|nvidia|cohere|groq|together|huggingface|cerebras|venice|synthetic|github-copilot)
+      echo "⚠️  Custom provider skipped: CUSTOM_PROVIDER_NAME='$CUSTOM_PROVIDER_NAME' conflicts with a built-in provider."
+      CUSTOM_PROVIDER_OK=false
+      ;;
+  esac
+
+  if [[ "$CUSTOM_BASE_URL_NORMALIZED" == */chat/completions ]] || [[ "$CUSTOM_BASE_URL_NORMALIZED" == */completions ]]; then
+    echo "⚠️  Custom provider skipped: CUSTOM_BASE_URL should be the API base URL, not a completions endpoint."
+    CUSTOM_PROVIDER_OK=false
+  fi
+
+  if ! [[ "$CUSTOM_CONTEXT_WINDOW" =~ ^[0-9]+$ ]] || ! [[ "$CUSTOM_MAX_TOKENS" =~ ^[0-9]+$ ]]; then
+    echo "⚠️  Custom provider skipped: CUSTOM_CONTEXT_WINDOW and CUSTOM_MAX_TOKENS must be whole numbers."
+    CUSTOM_PROVIDER_OK=false
+  fi
+
+  if [ "$CUSTOM_PROVIDER_OK" = "true" ]; then
+    echo "🔧 Registering custom provider: $CUSTOM_PROVIDER_NAME → $CUSTOM_BASE_URL_NORMALIZED"
+    CONFIG_JSON=$(jq \
+      --arg provider "$CUSTOM_PROVIDER_NAME" \
+      --arg baseUrl "$CUSTOM_BASE_URL_NORMALIZED" \
+      --arg apiKey "$CUSTOM_API_KEY" \
+      --arg apiType "$CUSTOM_API_TYPE" \
+      --arg modelId "$CUSTOM_MODEL_ID" \
+      --arg modelName "$CUSTOM_MODEL_NAME" \
+      --argjson contextWindow "$CUSTOM_CONTEXT_WINDOW" \
+      --argjson maxTokens "$CUSTOM_MAX_TOKENS" \
+      '.models.mode = "merge" |
+       .models.providers[$provider] = {
+         "baseUrl": $baseUrl,
+         "apiKey": $apiKey,
+         "api": $apiType,
+         "models": [{
+           "id": $modelId,
+           "name": $modelName,
+           "contextWindow": $contextWindow,
+           "maxTokens": $maxTokens
+         }]
+       }' <<<"$CONFIG_JSON")
+
+    if [[ "$LLM_MODEL" != "$CUSTOM_PROVIDER_NAME/"* ]]; then
+      echo "⚠️  Custom provider registered, but LLM_MODEL='$LLM_MODEL' does not start with '$CUSTOM_PROVIDER_NAME/'."
+    fi
+  fi
+fi
+
 # Browser configuration (managed local Chromium in HF/Docker)
 BROWSER_EXECUTABLE_PATH=""
 for candidate in /usr/bin/chromium /usr/bin/chromium-browser /snap/bin/chromium; do