Merge pull request #21 from anurag008w/main

Enhance Jupyter security, environment builder UX, and browser reliability

.env.example

@@ -131,12 +131,29 @@ LLM_MODEL=anthropic/claude-sonnet-4-5
 # Keys are rotated round-robin on every request — useful when you
 # have multiple accounts or want to spread rate-limit quota.
 #
+# Smart backoff: when a key gets a 429/402 response, it is temporarily
+# suspended so other keys handle traffic.
+#   Strike 1 → suspended for KEY_BLACKLIST_COOLDOWN_MS   (default 60 s)
+#   Strike 2 → suspended for KEY_BLACKLIST_COOLDOWN_MS × 4 (default 4 min)
+#   Strike 3 → suspended for 24 h  (quota likely exhausted — skipped all day)
+# A successful response resets the strike counter for that key.
+#
 # Pattern: <PROVIDER>_API_KEYS=key1,key2,key3
 # Fallback order: plural pool → singular key → LLM_API_KEY (optional)
 # Set false only if you want to disable global LLM_API_KEY fallback
 # across providers.
 LLM_API_KEY_FALLBACK_ENABLED=true
 #
+# Base backoff duration (ms) after the first 429 on a key (default: 60 s).
+# Increases exponentially on repeated failures.
+# KEY_BLACKLIST_COOLDOWN_MS=60000
+#
+# Number of consecutive 429/quota errors before a key is suspended for 24 h.
+# KEY_MAX_STRIKES=3
+#
+# Note: KIMI_API_KEYS and MOONSHOT_API_KEYS share the same API endpoint
+# (api.moonshot.cn) and are combined into one rotation pool automatically.
+#
 # Uncomment and fill in only the providers you use:
 #
 # ANTHROPIC_API_KEYS=sk-ant-key1,sk-ant-key2,sk-ant-key3
@@ -147,7 +164,8 @@ LLM_API_KEY_FALLBACK_ENABLED=true
 # KILOCODE_API_KEYS=key1,key2
 # OPENCODE_API_KEYS=key1,key2
 # ZAI_API_KEYS=key1,key2
-# MOONSHOT_API_KEYS=key1,key2
+# MOONSHOT_API_KEYS=key1,key2   # combines with KIMI_API_KEYS
+# KIMI_API_KEYS=key1,key2       # combines with MOONSHOT_API_KEYS
 # MINIMAX_API_KEYS=key1,key2
 # XIAOMI_API_KEYS=key1,key2
 # VOLCANO_ENGINE_API_KEYS=key1,key2
@@ -248,8 +266,8 @@ LLM_API_KEY_FALLBACK_ENABLED=true
 GATEWAY_TOKEN=your_gateway_token_here
 
 # [OPTIONAL] JupyterLab terminal token for /terminal/
-# Defaults to "huggingface" if unset. Set a strong token for private deployments.
-JUPYTER_TOKEN=huggingface
+# Set a strong token for private deployments. Must NOT be "huggingface".
+JUPYTER_TOKEN=run: openssl rand -hex 32
 
 # (Optional) Password auth — simpler alternative to token for casual users
 # If set, users can log in with this password instead of the token
@@ -288,14 +306,7 @@ HF_TOKEN=hf_your_token_here
 # Default: huggingclaw-backup
 BACKUP_DATASET_NAME=huggingclaw-backup
 
-# Git commit identity for workspace syncs
-WORKSPACE_GIT_USER=openclaw@example.com
-WORKSPACE_GIT_NAME=OpenClaw Bot
-
 # ── OPTIONAL: Background Services ──
-# Keep-alive ping interval (seconds). Default: 300. Set 0 to disable.
-KEEP_ALIVE_INTERVAL=300
-
 # Workspace auto-sync interval (seconds). Default: 180.
 SYNC_INTERVAL=180
 
@@ -305,6 +316,9 @@ OPENCLAW_CONFIG_WATCH_INTERVAL=1
 # Wait for openclaw.json to stay valid and unchanged before syncing. Default: 3.
 OPENCLAW_CONFIG_SETTLE_SECONDS=3
 
+# Minimum gap between sessions-triggered immediate syncs (seconds). Default: 30.
+SESSIONS_MIN_SYNC_GAP=30
+
 # Webhooks: Standard POST notifications for lifecycle events
 # WEBHOOK_URL=https://your-webhook-endpoint.com/log
 

Dockerfile

@@ -23,9 +23,12 @@ ARG DEV_MODE=false
 RUN apt-get update && apt-get install -y --no-install-recommends \
     git \
     sudo \
+    file \
     ca-certificates \
     jq \
     curl \
+    dbus \
+    dbus-x11 \
     python3 \
     python3-pip \
     chromium \
@@ -107,6 +110,7 @@ RUN chmod +x /home/node/app/start.sh \
               /home/node/app/cloudflare-proxy-setup.py \
               /home/node/app/cloudflare-keepalive-setup.py \
               /home/node/app/openclaw-sync.py \
+              /home/node/app/jupyter-devdata-sync.py \
               /home/node/app/multi-provider-key-rotator.cjs
 
 USER node

README.md

@@ -57,7 +57,6 @@ secrets:
 - [💻 Local Development](#-local-development)
 - [🔗 CLI Access](#-cli-access)
 - [💻 JupyterLab Terminal](#-jupyterlab-terminal)
-- [🔍 Merge Comparison](#-merge-comparison)
 - [🏗️ Architecture](#-architecture)
 - [💓 Staying Alive](#-staying-alive)
 - [🐛 Troubleshooting](#-troubleshooting)
@@ -178,6 +177,7 @@ HuggingClaw automatically syncs your workspace (chats, settings, sessions) to a
 | `SYNC_INTERVAL` | `180` | Full backup frequency in seconds |
 | `OPENCLAW_CONFIG_WATCH_INTERVAL` | `1` | How often to check `openclaw.json` for immediate settings sync |
 | `OPENCLAW_CONFIG_SETTLE_SECONDS` | `3` | How long `openclaw.json` must stay valid and unchanged before syncing |
+| `SESSIONS_MIN_SYNC_GAP` | `30` | Minimum seconds between session-triggered immediate syncs |
 
 ## 📦 Ephemeral Package Re-install *(Optional)*
 
@@ -242,7 +242,7 @@ Configure password access and network restrictions:
 
 | Variable | Default | Description |
 | :--- | :--- | :--- |
-| `OPENCLAW_PASSWORD` | — | Enable simple password auth instead of token |
+| `OPENCLAW_PASSWORD` | — | Enable simple password auth instead of token (applies only when `GATEWAY_TOKEN` is empty) |
 | `TRUSTED_PROXIES` | — | Comma-separated IPs of HF proxies |
 | `ALLOWED_ORIGINS` | — | Comma-separated allowed origins for Control UI |
 | `CLOUDFLARE_KEEPALIVE_ENABLED` | `true` | Set to `false` to disable the automatic Cloudflare KeepAlive worker |
@@ -371,20 +371,11 @@ The merged Space includes the Hugging Face JupyterLab template behavior inside t
 | `/app/` | OpenClaw Control UI | `7860` | Mounted behind the local reverse proxy |
 | `/terminal/` | JupyterLab terminal | `8888` | Auto-enabled when `GATEWAY_TOKEN` is set; uses `GATEWAY_TOKEN` as auth token unless `JUPYTER_TOKEN` is set separately. Set `DEV_MODE=false` to disable. |
 
-When enabled, the terminal notebook root is `/home/node`, so you can inspect HuggingClaw files, logs, workspace state, and runtime scripts from the browser.
+When enabled, the terminal notebook root defaults to `/home/node` (stable + writable by default). To browse a broader tree, set `JUPYTER_ROOT_DIR=/home`. Handy shortcuts are also created: `HuggingClaw`, `HuggingClaw-Workspace`, and `OpenClaw-Home`.
 
 > [!IMPORTANT]
 > No extra secret needed — `GATEWAY_TOKEN` is automatically reused as `JUPYTER_TOKEN`. Set a separate `JUPYTER_TOKEN` secret only if you want a different terminal credential.
 
-## 🔍 Merge Comparison
-
-This repository is a merge of two sources:
-
-- `anurag162008/HuggingClaw`: OpenClaw gateway, dashboard, Cloudflare proxy/keep-alive, Telegram/WhatsApp helpers, backup sync, key rotation, docs, and security metadata.
-- Hugging Face `SpacesExamples/jupyterlab` template: JupyterLab Docker behavior, token login UX, Hugging Face-branded login template, pinned Jupyter packages, and Git LFS defaults for large model/data artifacts.
-
-The main merge-specific change is the single-port router: HF Spaces exposes `7861`, while the router keeps OpenClaw at `/app/` and JupyterLab at `/terminal/` without leaking internal redirects such as `http://127.0.0.1:8888/...`.
-
 ## 🏗️ Architecture
 
 HuggingClaw uses a multi-layered approach to ensure stability and persistence on Hugging Face's ephemeral infrastructure.

cloudflare-proxy-setup.py

@@ -12,7 +12,8 @@ from pathlib import Path
 API_BASE = "https://api.cloudflare.com/client/v4"
 ENV_FILE = Path("/tmp/huggingclaw-cloudflare-proxy.env")
 DEFAULT_ALLOWED = [
-    # Messaging
+    # Messaging & social platforms — primary use-case for the Cloudflare proxy
+    # on HF Spaces (geo-restrictions on Telegram, Discord, WhatsApp, etc.).
     "api.telegram.org",
     "discord.com",
     "discordapp.com",
@@ -32,8 +33,6 @@ DEFAULT_ALLOWED = [
     # Video
     "youtube.com",
     "www.youtube.com",
-    # AI APIs
-    "api.openai.com",
     # Email HTTP APIs (SMTP ports are blocked; use these instead)
     "api.resend.com",
     "api.sendgrid.com",
@@ -43,6 +42,11 @@ DEFAULT_ALLOWED = [
     "google.com",
     "googleusercontent.com",
     "gstatic.com",
+    # NOTE: AI-provider domains (api.openai.com, api.anthropic.com, etc.) are
+    # intentionally NOT included here. Proxying AI calls routes API keys through
+    # the Cloudflare Worker without an explicit opt-in. Users who need AI API
+    # calls proxied (e.g. geo-restricted regions) can add specific domains via
+    # the CLOUDFLARE_PROXY_DOMAINS environment variable.
 ]
 
 

cloudflare-proxy.js

@@ -24,6 +24,8 @@ if (
 const DEBUG = process.env.CLOUDFLARE_PROXY_DEBUG === "true";
 const PROXY_SHARED_SECRET = (process.env.CLOUDFLARE_PROXY_SECRET || "").trim();
 const DEFAULT_PROXY_DOMAINS = [
+  // Messaging & social platforms — these are the primary use-case for the
+  // Cloudflare proxy on HF Spaces (geo-restrictions on Telegram, Discord, WA).
   "api.telegram.org", "discord.com", "discordapp.com",
   "gateway.discord.gg", "status.discord.com", "web.whatsapp.com",
   "graph.facebook.com", "graph.instagram.com",
@@ -31,10 +33,15 @@ const DEFAULT_PROXY_DOMAINS = [
   "api.linkedin.com", "www.linkedin.com",
   "open.tiktokapis.com", "oauth.reddit.com",
   "youtube.com", "www.youtube.com",
-  "api.openai.com",
-  "integrate.api.nvidia.com", "api.nvidia.com",
+  // Email delivery
   "api.resend.com", "api.sendgrid.com", "api.mailgun.net",
+  // Google services
   "googleapis.com", "google.com", "googleusercontent.com", "gstatic.com",
+  // NOTE: AI-provider domains (api.openai.com, api.anthropic.com, etc.) are
+  // intentionally NOT included here. Proxying AI calls routes your API keys
+  // through the Cloudflare Worker without an explicit opt-in. Users who need
+  // AI API calls proxied (e.g. geo-restricted regions) can add specific
+  // domains via the CLOUDFLARE_PROXY_DOMAINS environment variable.
 ];
 const PROXY_DOMAINS_RAW = (process.env.CLOUDFLARE_PROXY_DOMAINS || "").trim();
 const PROXY_ALL = PROXY_DOMAINS_RAW === "*";

env-builder.html

@@ -37,16 +37,16 @@
   --panel-w:   340px;
 }
 
-html { scroll-behavior: smooth; }
+html { scroll-behavior: smooth; height: 100%; }
 
 body {
   font-family: var(--sans);
   background: var(--bg);
   color: var(--text);
-  min-height: 100vh;
+  height: 100vh;
+  overflow: hidden;
   display: flex;
   flex-direction: column;
-  overflow-x: hidden;
 }
 
 /* ── Topbar ── */
@@ -130,6 +130,7 @@ body {
   background: var(--bg2);
   display: flex;
   flex-direction: column;
+  min-height: 0;
   overflow: hidden;
 }
 
@@ -330,6 +331,15 @@ body {
   letter-spacing: 1.2px;
   color: var(--text3);
 }
+.sec-count {
+  font-family: var(--mono);
+  font-size: 10px;
+  color: var(--text3);
+  background: var(--bg3);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 1px 7px;
+}
 
 .sec-line {
   flex: 1;
@@ -339,8 +349,8 @@ body {
 
 .cards {
   display: grid;
-  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-  gap: 10px;
+  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  gap: 9px;
 }
 
 /* ── ENV Card ── */
@@ -360,6 +370,22 @@ body {
   background: linear-gradient(135deg, var(--bg2) 80%, rgba(245,166,35,.04));
 }
 
+/* Critical cards get a red left-border accent */
+.env-card:has(.badge-critical) {
+  border-left: 3px solid rgba(240,80,80,.4);
+}
+.env-card:has(.badge-critical):hover {
+  border-left-color: rgba(240,80,80,.7);
+}
+.env-card:has(.badge-critical).selected {
+  border-left-color: #f05f5f;
+}
+
+/* Credential cards get an amber left-border accent */
+.env-card:has(.badge-credential) {
+  border-left: 3px solid rgba(220,140,60,.3);
+}
+
 .card-top {
   display: flex;
   align-items: flex-start;
@@ -407,16 +433,46 @@ body {
   border-radius: 20px;
 }
 
-.badge-s {
-  background: rgba(240,95,95,.12);
-  color: var(--red);
-  border: 1px solid rgba(240,95,95,.25);
+/* critical — space breaks without this */
+.badge-critical {
+  background: rgba(240,80,80,.14);
+  color: #f05f5f;
+  border: 1px solid rgba(240,80,80,.3);
 }
 
-.badge-f {
-  background: rgba(61,214,140,.1);
-  color: var(--green);
-  border: 1px solid rgba(61,214,140,.2);
+/* credential — sensitive key / token */
+.badge-credential {
+  background: rgba(220,140,60,.13);
+  color: #e09040;
+  border: 1px solid rgba(220,140,60,.28);
+}
+
+/* feature — enables an optional feature */
+.badge-feature {
+  background: rgba(70,140,250,.12);
+  color: #5a9eff;
+  border: 1px solid rgba(70,140,250,.25);
+}
+
+/* optional — safe to change freely */
+.badge-optional {
+  background: rgba(61,214,140,.10);
+  color: #3dd68c;
+  border: 1px solid rgba(61,214,140,.22);
+}
+
+/* advanced — power-user, risky if wrong */
+.badge-advanced {
+  background: rgba(160,100,230,.12);
+  color: #b07ae0;
+  border: 1px solid rgba(160,100,230,.25);
+}
+
+/* build-time — needs HF Space rebuild */
+.badge-build {
+  background: rgba(240,185,60,.12);
+  color: #e0b030;
+  border: 1px solid rgba(240,185,60,.28);
 }
 
 /* ── Card inputs ── */
@@ -522,6 +578,7 @@ body {
 .panel-scroll {
   flex: 1;
   overflow-y: auto;
+  min-height: 0;
   padding: 16px;
   display: flex;
   flex-direction: column;
@@ -679,6 +736,10 @@ body {
 ::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 4px; }
 
 /* ── Responsive ── */
+
+@media (max-width: 1100px) {
+  .toolbar-hint { display: none; }
+}
 @media (max-width: 900px) {
   :root { --panel-w: 280px; --sidebar-w: 180px; }
 }
@@ -692,6 +753,57 @@ body {
   .sidebar-wrap { display: none; }
   .topbar-divider, .topbar-title { display: none; }
 }
+
+/* ── Tag Legend (collapsible) ── */
+.tag-legend {
+  margin-bottom: 14px;
+  background: var(--bg2);
+  border: 1px solid var(--border);
+  border-radius: var(--r);
+  overflow: hidden;
+}
+.legend-summary {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 7px 12px;
+  cursor: pointer;
+  list-style: none;
+  user-select: none;
+  outline: none;
+}
+.legend-summary::-webkit-details-marker { display: none; }
+.legend-chips { display: flex; gap: 5px; flex-wrap: wrap; flex: 1; }
+.legend-hint {
+  font-size: 10px;
+  color: var(--text3);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.tag-legend[open] .legend-hint { opacity: 0; }
+.toolbar-hint { color: var(--muted); font-size: 12px; margin-right: 10px; white-space: nowrap; }
+.legend-body {
+  padding: 8px 12px 10px;
+  border-top: 1px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.legend-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 11px;
+  color: var(--text2);
+}
+.legend-row .badge { flex-shrink: 0; width: 74px; text-align: center; }
+.legend-tip {
+  font-size: 9.5px;
+  color: var(--text3);
+  margin-top: 4px;
+  padding-top: 6px;
+  border-top: 1px solid var(--border);
+}
 </style>
 </head>
 
@@ -729,6 +841,7 @@ body {
 
     <!-- toolbar -->
     <div class="toolbar">
+      <div class="toolbar-hint">Tip: Start with <strong>⚡ Required</strong>, then fill keys and click <strong># Generate Bundle</strong>.</div>
       <div class="search-wrap">
         <span class="search-icon">⌕</span>
         <input id="search" type="text" placeholder="Search variables…" autocomplete="off" spellcheck="false">
@@ -736,6 +849,7 @@ body {
 
       <div class="tb-sep"></div>
 
+      <button id="selectRequired" class="btn" title="Select all critical variables first">⚡ Required</button>
       <button id="selectCommon" class="btn">★ Common</button>
       <button id="selectVisible" class="btn">☑ Visible</button>
       <button id="clearAll" class="btn btn-ghost">✕ Clear</button>
@@ -746,6 +860,29 @@ body {
 
       <!-- sections -->
       <div class="sections-scroll">
+        <!-- Tag Legend (compact collapsible) -->
+        <details class="tag-legend" id="tagLegend">
+          <summary class="legend-summary">
+            <span class="legend-chips">
+              <span class="badge badge-critical">critical</span>
+              <span class="badge badge-credential">credential</span>
+              <span class="badge badge-feature">feature</span>
+              <span class="badge badge-optional">optional</span>
+              <span class="badge badge-advanced">advanced</span>
+              <span class="badge badge-build">build-time</span>
+            </span>
+            <span class="legend-hint">what do these mean?</span>
+          </summary>
+          <div class="legend-body">
+            <div class="legend-row"><span class="badge badge-critical">critical</span><span>Space won't work without this</span></div>
+            <div class="legend-row"><span class="badge badge-credential">credential</span><span>Sensitive key or token — never share</span></div>
+            <div class="legend-row"><span class="badge badge-feature">feature</span><span>Enables a specific optional feature</span></div>
+            <div class="legend-row"><span class="badge badge-optional">optional</span><span>Safe to change — nothing breaks</span></div>
+            <div class="legend-row"><span class="badge badge-advanced">advanced</span><span>Power-user setting — wrong value causes issues</span></div>
+            <div class="legend-row"><span class="badge badge-build">build-time</span><span>Needs HF Space rebuild to fully take effect</span></div>
+            <div class="legend-tip">💡 Type a tag name in search to filter by it</div>
+          </div>
+        </details>
         <div id="sections"></div>
 
         <!-- Custom Env section -->
@@ -764,7 +901,6 @@ body {
       <aside class="right-panel">
         <div class="panel-scroll">
 
-          <!-- Summary -->
           <div class="pblock">
             <div class="pblock-head">
               <span class="pblock-title">📊 Summary</span>
@@ -780,7 +916,8 @@ body {
               <span class="pblock-title">📦 Bundle Output</span>
             </div>
             <div class="pblock-body">
-              <textarea id="bundleOut" placeholder="Your encoded bundle will appear here…" readonly spellcheck="false"></textarea>
+              <button id="generateBundle" class="btn btn-amber" style="width:100%;font-size:12.5px;"># Generate Bundle</button>
+              <textarea id="bundleOut" placeholder="Click # Generate to build your bundle…" readonly spellcheck="false"></textarea>
               <input type="text" id="envLineOut" placeholder="HUGGINGCLAW_ENV_BUNDLE=…" readonly spellcheck="false">
               <div class="row-btns">
                 <button id="copyBundle" class="btn btn-amber">⎘ Bundle</button>

env-builder.js

@@ -54,25 +54,25 @@ const MODEL_CATALOGS = {
     "Groq": [
       "groq/compound",
       "groq/compound-mini",
-      "llama-3.1-8b-instant",
-      "llama-3.1-70b-versatile",
-      "llama-3.3-70b-versatile",
+      "groq/llama-3.1-8b-instant",
+      "groq/llama-3.1-70b-versatile",
+      "groq/llama-3.3-70b-versatile",
       "meta-llama/llama-4-scout-17b-16e-instruct",
       "openai/gpt-oss-20b",
       "openai/gpt-oss-120b",
       "qwen/qwen3-32b",
-      "mixtral-8x7b-32768"
+      "groq/mixtral-8x7b-32768"
     ],
     "Mistral": [
-      "mistral-large-latest",
-      "mistral-large-2",
-      "mistral-medium-3.5",
-      "mistral-small-latest",
-      "mistral-small-3.2",
-      "devstral-2",
-      "ocr-3-premier",
-      "voxtral-mini-transcribe-realtime",
-      "codestral-latest"
+      "mistral/mistral-large-latest",
+      "mistral/mistral-large-2",
+      "mistral/mistral-medium-3.5",
+      "mistral/mistral-small-latest",
+      "mistral/mistral-small-3.2",
+      "mistral/devstral-2",
+      "mistral/ocr-3-premier",
+      "mistral/voxtral-mini-transcribe-realtime",
+      "mistral/codestral-latest"
     ],
     "Cohere": [
       "command-a",
@@ -280,25 +280,25 @@ const MODEL_CATALOGS = {
   "GROQ_MODELS": [
     "groq/compound",
     "groq/compound-mini",
-    "llama-3.1-8b-instant",
-    "llama-3.1-70b-versatile",
-    "llama-3.3-70b-versatile",
+    "groq/llama-3.1-8b-instant",
+    "groq/llama-3.1-70b-versatile",
+    "groq/llama-3.3-70b-versatile",
     "openai/gpt-oss-20b",
     "openai/gpt-oss-120b",
     "meta-llama/llama-4-scout-17b-16e-instruct",
     "qwen/qwen3-32b",
-    "mixtral-8x7b-32768"
+    "groq/mixtral-8x7b-32768"
   ],
   "MISTRAL_MODELS": [
-    "mistral-large-latest",
-    "mistral-large-2",
-    "mistral-medium-3.5",
-    "mistral-small-latest",
-    "mistral-small-3.2",
-    "devstral-2",
-    "ocr-3-premier",
-    "voxtral-mini-transcribe-realtime",
-    "codestral-latest"
+    "mistral/mistral-large-latest",
+    "mistral/mistral-large-2",
+    "mistral/mistral-medium-3.5",
+    "mistral/mistral-small-latest",
+    "mistral/mistral-small-3.2",
+    "mistral/devstral-2",
+    "mistral/ocr-3-premier",
+    "mistral/voxtral-mini-transcribe-realtime",
+    "mistral/codestral-latest"
   ],
   "XAI_MODELS": [
     "grok-4.3",
@@ -416,200 +416,247 @@ const MODEL_CATALOGS = {
 };
 
 const FIELDS = [
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "LLM_MODEL",
     "lbl": "Default model ID",
-    "type": "model",
-    "options_key": "LLM_MODEL",
+    "type": "text",
     "ph": "choose a provider model",
-    "common": 1
+    "common": 1,
+    "tag": "critical"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "LLM_API_KEY",
     "lbl": "Primary provider API key",
     "type": "password",
-    "secret": 1,
     "ph": "sk-...",
-    "common": 1
+    "common": 1,
+    "tag": "credential"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "GATEWAY_TOKEN",
     "lbl": "Control UI gateway token",
     "type": "password",
-    "secret": 1,
-    "common": 1
+    "common": 1,
+    "tag": "critical"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "OPENCLAW_PASSWORD",
     "lbl": "Optional password auth",
     "type": "password",
-    "secret": 1
+    "tag": "credential"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "OPENCLAW_VERSION",
-    "lbl": "Pin OpenClaw version",
+    "lbl": "Pin OpenClaw version (build-time; rebuild required)",
     "type": "text",
-    "ph": "latest"
+    "ph": "latest",
+    "tag": "build"
   },
-  {
-    "g": "Core",
+{
+    "g": "Plugins",
     "icon": "⚡",
     "k": "LLM_API_KEY_FALLBACK_ENABLED",
     "lbl": "Allow global LLM_API_KEY fallback",
     "type": "toggle",
-    "ph": "true"
+    "ph": "true",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Plugins",
+    "icon": "🔄",
+    "k": "KEY_BLACKLIST_COOLDOWN_MS",
+    "lbl": "Key rotation base backoff (ms) — time a key is skipped after first 429/rate-limit (doubles on repeated failures; 24h after max strikes)",
+    "type": "text",
+    "ph": "60000",
+    "tag": "advanced"
+  },
+{
+    "g": "Plugins",
+    "icon": "🔄",
+    "k": "KEY_MAX_STRIKES",
+    "lbl": "Key rotation max strikes — consecutive 429/quota errors before a key is suspended for 24h",
+    "type": "text",
+    "ph": "3",
+    "tag": "advanced"
+  },
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "DEV_MODE",
     "lbl": "Enable dev mode",
     "type": "toggle",
     "ph": "false",
-    "common": 1
+    "common": 1,
+    "tag": "build"
+  },
+{
+    "g": "Startup",
+    "icon": "🩺",
+    "k": "AUTO_DOCTOR",
+    "lbl": "Auto-fix config on boot (openclaw doctor --fix)",
+    "type": "toggle",
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_JUPYTER_ENABLED",
     "lbl": "Enable Jupyter terminal",
     "type": "toggle",
     "ph": "false",
-    "common": 1
+    "common": 1,
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "DevData",
     "icon": "⚡",
     "k": "DEVDATA",
     "lbl": "DevData switch",
     "type": "toggle",
     "ph": "on",
-    "common": 1
+    "common": 1,
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "DevData",
     "icon": "⚡",
     "k": "DEVDATA_DATASET_NAME",
     "lbl": "DevData dataset name",
     "type": "text",
     "ph": "huggingclaw-devdata",
-    "common": 1
+    "common": 1,
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "DevData",
     "icon": "⚡",
     "k": "DEVDATA_SYNC_INTERVAL",
     "lbl": "DevData sync interval (seconds)",
     "type": "number",
-    "ph": "180"
+    "ph": "180",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "WhatsApp",
     "icon": "⚡",
     "k": "WHATSAPP_ENABLED",
     "lbl": "Enable WhatsApp pairing",
     "type": "toggle",
     "ph": "false",
-    "common": 1
+    "common": 1,
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_CAPTURE_DISABLE",
     "lbl": "Disable capture wrapper",
     "type": "toggle",
-    "ph": "false"
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_STARTUP_STRICT",
     "lbl": "Stop on startup failure",
     "type": "toggle",
-    "ph": "false"
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_RUN",
     "lbl": "Startup command (one-liner)",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_STARTUP_COMMANDS",
     "lbl": "Multiline startup commands",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_STARTUP_SCRIPT",
     "lbl": "Startup shell script",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_STARTUP_SCRIPT_B64",
     "lbl": "Startup script (base64)",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_APT_PACKAGES",
     "lbl": "APT packages to install",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_PIP_PACKAGES",
     "lbl": "Pip packages to install",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_NPM_PACKAGES",
     "lbl": "NPM packages to install",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Startup",
     "icon": "⚡",
     "k": "HUGGINGCLAW_OPENCLAW_PLUGINS",
     "lbl": "OpenClaw plugins to load",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Network",
     "icon": "⚡",
     "k": "ALLOWED_ORIGINS",
     "lbl": "Allowed CORS origins",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Network",
     "icon": "⚡",
     "k": "TRUSTED_PROXIES",
     "lbl": "Trusted proxy CIDRs",
-    "type": "textarea"
+    "type": "textarea",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Network",
     "icon": "⚡",
     "k": "WEBHOOK_URL",
     "lbl": "Webhook URL",
@@ -622,34 +669,38 @@ const FIELDS = [
     "k": "GATEWAY_MAX_RESTARTS",
     "lbl": "Gateway max restarts",
     "type": "number",
-    "ph": "10"
+    "ph": "10",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Gateway",
     "icon": "⚡",
     "k": "GATEWAY_READY_TIMEOUT",
     "lbl": "Gateway ready timeout",
     "type": "number",
-    "ph": "90"
+    "ph": "90",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Gateway",
     "icon": "⚡",
     "k": "GATEWAY_RESTART_DELAY",
     "lbl": "Gateway restart delay",
     "type": "number",
-    "ph": "5"
+    "ph": "5",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Gateway",
     "icon": "⚡",
     "k": "GATEWAY_VERBOSE",
     "lbl": "Verbose gateway logs",
     "type": "toggle",
-    "ph": "false"
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Logging",
     "icon": "⚡",
     "k": "OPENCLAW_CONSOLE_LOG_LEVEL",
     "lbl": "Console log level",
@@ -660,10 +711,11 @@ const FIELDS = [
       "warn",
       "error"
     ],
-    "ph": "info"
+    "ph": "info",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Logging",
     "icon": "⚡",
     "k": "OPENCLAW_FILE_LOG_LEVEL",
     "lbl": "File log level",
@@ -674,10 +726,11 @@ const FIELDS = [
       "warn",
       "error"
     ],
-    "ph": "info"
+    "ph": "info",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Logging",
     "icon": "⚡",
     "k": "OPENCLAW_CONSOLE_LOG_STYLE",
     "lbl": "Console log style",
@@ -687,10 +740,11 @@ const FIELDS = [
       "json",
       "compact"
     ],
-    "ph": "pretty"
+    "ph": "pretty",
+    "tag": "optional"
   },
-  {
-    "g": "Core",
+{
+    "g": "Plugins",
     "icon": "⚡",
     "k": "BROWSER_PLUGIN_MODE",
     "lbl": "Browser plugin mode",
@@ -700,10 +754,11 @@ const FIELDS = [
       "enabled",
       "disabled"
     ],
-    "ph": "auto"
+    "ph": "auto",
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "Plugins",
     "icon": "⚡",
     "k": "ACP_PLUGIN_MODE",
     "lbl": "ACP plugin mode",
@@ -713,98 +768,106 @@ const FIELDS = [
       "enabled",
       "disabled"
     ],
-    "ph": "auto"
+    "ph": "auto",
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_PROXY_DEBUG",
     "lbl": "Cloudflare proxy debug",
     "type": "toggle",
-    "ph": "false"
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_KEEPALIVE_ENABLED",
     "lbl": "Enable keep-awake worker",
     "type": "toggle",
-    "ph": "true"
+    "ph": "true",
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_PROXY_URL",
     "lbl": "Proxy worker URL",
     "type": "text",
     "ph": "https://your-proxy.workers.dev",
-    "common": 1
+    "common": 1,
+    "tag": "feature"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_PROXY_SECRET",
     "lbl": "Proxy shared secret",
     "type": "password",
-    "secret": 1
+    "tag": "credential"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_PROXY_DOMAINS",
     "lbl": "Extra domains to proxy",
     "type": "textarea",
-    "ph": "api.sendgrid.com,slack.com"
+    "ph": "api.sendgrid.com,slack.com",
+    "tag": "advanced"
   },
-  {
-    "g": "Core",
+{
+    "g": "Cloudflare",
     "icon": "⚡",
     "k": "CLOUDFLARE_WORKERS_TOKEN",
     "lbl": "Workers API token",
     "type": "password",
-    "secret": 1,
-    "common": 1
+    "common": 1,
+    "tag": "credential"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "HF_USERNAME",
     "lbl": "Hugging Face username",
     "type": "text",
-    "common": 1
+    "common": 1,
+    "tag": "optional"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "HF_TOKEN",
     "lbl": "HF write token",
     "type": "password",
-    "secret": 1,
-    "common": 1
+    "common": 1,
+    "tag": "credential"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "BACKUP_DATASET_NAME",
     "lbl": "Backup dataset name",
     "type": "text",
     "ph": "huggingclaw-backup",
-    "common": 1
+    "common": 1,
+    "tag": "optional"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "SYNC_INTERVAL",
     "lbl": "Sync interval (seconds)",
     "type": "number",
     "ph": "180",
-    "common": 1
+    "common": 1,
+    "tag": "advanced"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "JUPYTER_TOKEN",
-    "lbl": "Jupyter access token",
+    "lbl": "Jupyter access token (Must NOT be 'huggingface'. Run: openssl rand -hex 32)",
     "type": "password",
     "secret": 1,
     "ph": "huggingface",
@@ -816,95 +879,116 @@ const FIELDS = [
     "k": "OPENCLAW_DISABLE_BONJOUR",
     "lbl": "Disable Bonjour/mDNS discovery",
     "type": "toggle",
-    "ph": "false"
+    "ph": "false",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "OPENCLAW_RUNTIME_VERSION",
     "lbl": "Pin runtime version",
     "type": "text",
-    "ph": "latest"
+    "ph": "latest",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Core",
     "icon": "⚡",
     "k": "OPENCLAW_DISPLAY_VERSION",
     "lbl": "Display version label",
     "type": "text",
-    "ph": ""
+    "ph": "",
+    "tag": "optional"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "CLOUDFLARE_ACCOUNT_ID",
     "lbl": "Cloudflare account ID",
     "type": "text",
-    "ph": "account-id"
+    "ph": "account-id",
+    "tag": "feature"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "CLOUDFLARE_WORKER_NAME",
     "lbl": "Outbound proxy worker name",
     "type": "text",
-    "ph": "huggingclaw-proxy"
+    "ph": "huggingclaw-proxy",
+    "tag": "feature"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "CLOUDFLARE_KEEPALIVE_URL",
     "lbl": "Keepalive worker URL",
     "type": "text",
-    "ph": "https://your-worker.workers.dev"
+    "ph": "https://your-worker.workers.dev",
+    "tag": "feature"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "CLOUDFLARE_KEEPALIVE_WORKER_NAME",
     "lbl": "Keepalive worker name",
     "type": "text",
-    "ph": "huggingclaw-keepalive"
+    "ph": "huggingclaw-keepalive",
+    "tag": "feature"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "CLOUDFLARE_KEEPALIVE_CRON",
     "lbl": "Keepalive cron schedule",
     "type": "text",
-    "ph": "*/5 * * * *"
+    "ph": "*/5 * * * *",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Integrations",
     "icon": "🔌",
     "k": "TELEGRAM_API_ROOT",
     "lbl": "Telegram API root override",
     "type": "text",
-    "ph": "https://api.telegram.org"
+    "ph": "https://api.telegram.org",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Runtime",
     "icon": "⚙️",
     "k": "OPENCLAW_CONFIG_WATCH_INTERVAL",
     "lbl": "Config watch interval (seconds)",
     "type": "number",
-    "ph": "1"
+    "ph": "1",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Runtime",
     "icon": "⚙️",
     "k": "OPENCLAW_CONFIG_SETTLE_SECONDS",
     "lbl": "Config settle window (seconds)",
     "type": "number",
-    "ph": "3"
+    "ph": "3",
+    "tag": "advanced"
   },
-  {
+{
+    "g": "Runtime",
+    "icon": "⚙️",
+    "k": "SESSIONS_MIN_SYNC_GAP",
+    "lbl": "Sessions min sync gap (seconds)",
+    "type": "number",
+    "ph": "30",
+    "tag": "advanced"
+  },
+{
     "g": "Runtime",
     "icon": "⚙️",
     "k": "JUPYTER_ROOT_DIR",
     "lbl": "Jupyter root directory",
     "type": "text",
-    "ph": "/home/node"
+    "ph": "/home/node",
+    "tag": "advanced"
   },
   {
     "g": "Provider Keys",
@@ -912,663 +996,711 @@ const FIELDS = [
     "k": "ANTHROPIC_API_KEY",
     "lbl": "Anthropic (Claude)",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "OPENAI_API_KEY",
     "lbl": "OpenAI (GPT)",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "GEMINI_API_KEY",
     "lbl": "Google Gemini",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "DEEPSEEK_API_KEY",
     "lbl": "DeepSeek",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "OPENROUTER_API_KEY",
     "lbl": "OpenRouter",
     "type": "password",
-    "secret": 1,
-    "common": 1
+    "common": 1,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "OPENCODE_API_KEY",
     "lbl": "OpenCode",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "KILOCODE_API_KEY",
     "lbl": "KiloCode",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "ZAI_API_KEY",
     "lbl": "Z.ai / GLM",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "MOONSHOT_API_KEY",
     "lbl": "Moonshot / Kimi",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "MINIMAX_API_KEY",
     "lbl": "MiniMax",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "XIAOMI_API_KEY",
     "lbl": "Xiaomi / MiMo",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "VOLCANO_ENGINE_API_KEY",
     "lbl": "Volcengine / Doubao",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "BYTEPLUS_API_KEY",
     "lbl": "BytePlus",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "MISTRAL_API_KEY",
     "lbl": "Mistral",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "XAI_API_KEY",
     "lbl": "xAI (Grok)",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "NVIDIA_API_KEY",
     "lbl": "NVIDIA",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "GROQ_API_KEY",
     "lbl": "Groq",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "COHERE_API_KEY",
     "lbl": "Cohere",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "TOGETHER_API_KEY",
     "lbl": "Together AI",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "CEREBRAS_API_KEY",
     "lbl": "Cerebras",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "QIANFAN_API_KEY",
     "lbl": "Qianfan",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "MODELSTUDIO_API_KEY",
     "lbl": "ModelStudio",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "KIMI_API_KEY",
     "lbl": "Kimi",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "HUGGINGFACE_HUB_TOKEN",
     "lbl": "Hugging Face token",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "COPILOT_GITHUB_TOKEN",
     "lbl": "GitHub Copilot",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "VENICE_API_KEY",
     "lbl": "Venice",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "SYNTHETIC_API_KEY",
     "lbl": "Synthetic",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Provider Keys",
     "icon": "🔑",
     "k": "AI_GATEWAY_API_KEY",
     "lbl": "AI Gateway",
     "type": "password",
-    "secret": 1,
-    "common": 0
+    "common": 0,
+    "tag": "credential"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "ANTHROPIC_API_KEYS",
     "lbl": "Anthropic pool (comma-sep)",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "OPENAI_API_KEYS",
     "lbl": "OpenAI pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "GEMINI_API_KEYS",
     "lbl": "Gemini pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "DEEPSEEK_API_KEYS",
     "lbl": "DeepSeek pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "OPENROUTER_API_KEYS",
     "lbl": "OpenRouter pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "OPENCODE_API_KEYS",
     "lbl": "OpenCode pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "KILOCODE_API_KEYS",
     "lbl": "KiloCode pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "ZAI_API_KEYS",
     "lbl": "Z.ai / GLM pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "MOONSHOT_API_KEYS",
-    "lbl": "Moonshot / Kimi pool",
-    "type": "text"
+    "lbl": "Moonshot pool (merged with KIMI_API_KEYS into one rotation pool)",
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "MINIMAX_API_KEYS",
     "lbl": "MiniMax pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "XIAOMI_API_KEYS",
     "lbl": "Xiaomi pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "VOLCANO_ENGINE_API_KEYS",
     "lbl": "Volcano Engine pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "BYTEPLUS_API_KEYS",
     "lbl": "BytePlus pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "MISTRAL_API_KEYS",
     "lbl": "Mistral pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "XAI_API_KEYS",
     "lbl": "xAI pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "NVIDIA_API_KEYS",
     "lbl": "NVIDIA pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "GROQ_API_KEYS",
     "lbl": "Groq pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "COHERE_API_KEYS",
     "lbl": "Cohere pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "TOGETHER_API_KEYS",
     "lbl": "Together pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "CEREBRAS_API_KEYS",
     "lbl": "Cerebras pool",
-    "type": "text"
+    "type": "text",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Rotation Pools",
     "icon": "🔄",
     "k": "HUGGINGFACE_HUB_TOKENS",
     "lbl": "HF token pool",
     "type": "text"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "OPENAI_MODELS",
     "lbl": "Visible OpenAI models",
     "type": "model_list",
     "options_key": "OPENAI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "ANTHROPIC_MODELS",
     "lbl": "Visible Anthropic models",
     "type": "model_list",
     "options_key": "ANTHROPIC_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "GEMINI_MODELS",
     "lbl": "Visible Gemini models",
     "type": "model_list",
     "options_key": "GEMINI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "DEEPSEEK_MODELS",
     "lbl": "Visible DeepSeek models",
     "type": "model_list",
     "options_key": "DEEPSEEK_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "OPENROUTER_MODELS",
     "lbl": "Visible OpenRouter models",
     "type": "model_list",
     "options_key": "OPENROUTER_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "GROQ_MODELS",
     "lbl": "Visible Groq models",
     "type": "model_list",
     "options_key": "GROQ_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "MISTRAL_MODELS",
     "lbl": "Visible Mistral models",
     "type": "model_list",
     "options_key": "MISTRAL_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "XAI_MODELS",
     "lbl": "Visible xAI models",
     "type": "model_list",
     "options_key": "XAI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "COHERE_MODELS",
     "lbl": "Visible Cohere models",
     "type": "model_list",
     "options_key": "COHERE_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "TOGETHER_MODELS",
     "lbl": "Visible Together models",
     "type": "model_list",
     "options_key": "TOGETHER_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "CEREBRAS_MODELS",
     "lbl": "Visible Cerebras models",
     "type": "model_list",
     "options_key": "CEREBRAS_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "NVIDIA_MODELS",
     "lbl": "Visible NVIDIA models",
     "type": "model_list",
     "options_key": "NVIDIA_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "KILOCODE_MODELS",
     "lbl": "Visible KiloCode models",
     "type": "model_list",
     "options_key": "KILOCODE_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "OPENCODE_MODELS",
     "lbl": "Visible OpenCode models",
     "type": "model_list",
     "options_key": "OPENCODE_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "ZAI_MODELS",
     "lbl": "Visible Z.ai / GLM models",
     "type": "model_list",
     "options_key": "ZAI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "MOONSHOT_MODELS",
     "lbl": "Visible Moonshot / Kimi models",
     "type": "model_list",
     "options_key": "MOONSHOT_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "MINIMAX_MODELS",
     "lbl": "Visible MiniMax models",
     "type": "model_list",
     "options_key": "MINIMAX_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "XIAOMI_MODELS",
     "lbl": "Visible Xiaomi models",
     "type": "model_list",
     "options_key": "XIAOMI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "VOLCANO_ENGINE_MODELS",
     "lbl": "Visible Volcano Engine models",
     "type": "model_list",
     "options_key": "VOLCANO_ENGINE_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "BYTEPLUS_MODELS",
     "lbl": "Visible BytePlus models",
     "type": "model_list",
     "options_key": "BYTEPLUS_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "QIANFAN_MODELS",
     "lbl": "Visible Qianfan models",
     "type": "model_list",
     "options_key": "QIANFAN_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "MODELSTUDIO_MODELS",
     "lbl": "Visible ModelStudio models",
     "type": "model_list",
     "options_key": "MODELSTUDIO_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "KIMI_MODELS",
     "lbl": "Visible Kimi models",
     "type": "model_list",
     "options_key": "KIMI_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "HUGGINGFACE_MODELS",
     "lbl": "Visible Hugging Face models",
     "type": "model_list",
     "options_key": "HUGGINGFACE_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Model Lists",
     "icon": "📋",
     "k": "GITHUB_COPILOT_MODELS",
     "lbl": "Visible GitHub Copilot models",
     "type": "model_list",
     "options_key": "GITHUB_COPILOT_MODELS",
-    "ph": "Select models to build a comma list"
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_PROVIDER_NAME",
     "lbl": "Provider display name",
-    "type": "text"
+    "type": "text",
+    "tag": "feature"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_BASE_URL",
     "lbl": "OpenAI-compatible base URL",
-    "type": "text"
+    "type": "text",
+    "tag": "feature"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_MODEL_ID",
     "lbl": "Model ID",
-    "type": "model",
-    "options_key": "LLM_MODEL",
-    "ph": "custom model id"
+    "type": "text",
+    "ph": "custom model id",
+    "tag": "feature"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_MODEL_NAME",
     "lbl": "Friendly model name",
-    "type": "text"
+    "type": "text",
+    "tag": "feature"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_API_KEY",
     "lbl": "Provider API key",
     "type": "password",
-    "secret": 1
+    "tag": "credential"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_API_TYPE",
@@ -1581,104 +1713,200 @@ const FIELDS = [
       "gemini",
       "openrouter"
     ],
-    "ph": "openai-completions"
+    "ph": "openai-completions",
+    "tag": "feature"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_CONTEXT_WINDOW",
     "lbl": "Context window",
     "type": "number",
-    "ph": "128000"
+    "ph": "128000",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Custom Provider",
     "icon": "🔌",
     "k": "CUSTOM_MAX_TOKENS",
     "lbl": "Max output tokens",
     "type": "number",
-    "ph": "500"
+    "ph": "8192",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Telegram",
     "icon": "✈️",
     "k": "TELEGRAM_BOT_TOKEN",
     "lbl": "Bot token from BotFather",
     "type": "password",
-    "secret": 1,
-    "common": 1
+    "common": 1,
+    "tag": "credential"
   },
-  {
+{
     "g": "Telegram",
     "icon": "✈️",
     "k": "TELEGRAM_ALLOWED_USERS",
     "lbl": "Allowed user IDs (comma)",
     "type": "text",
     "ph": "123456789,987654321",
-    "common": 1
+    "common": 1,
+    "tag": "critical"
   },
-  {
+{
+    "g": "Telegram",
+    "icon": "✈️",
+    "k": "TELEGRAM_USER_IDS",
+    "lbl": "Telegram user IDs (comma)",
+    "type": "text",
+    "tag": "optional"
+  },
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "APP_BASE",
     "lbl": "Public app base path",
     "type": "text",
-    "ph": "/app"
+    "ph": "/app",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "SPACE_AUTHOR_NAME",
     "lbl": "HF Space author name",
-    "type": "text"
+    "type": "text",
+    "tag": "optional"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "SPACE_HOST",
     "lbl": "HF Space host domain",
-    "type": "text"
+    "type": "text",
+    "tag": "optional"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "PORT",
     "lbl": "Public dashboard port",
     "type": "number",
-    "ph": "7861"
+    "ph": "7861",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "GATEWAY_PORT",
     "lbl": "OpenClaw internal port",
     "type": "number",
-    "ph": "7860"
+    "ph": "7860",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "JUPYTER_PORT",
     "lbl": "Jupyter internal port",
     "type": "number",
-    "ph": "8888"
+    "ph": "8888",
+    "tag": "advanced"
   },
-  {
+{
     "g": "Deployment",
     "icon": "🧭",
     "k": "JUPYTER_BASE",
     "lbl": "Jupyter public base path",
     "type": "text",
-    "ph": "/terminal"
+    "ph": "/terminal",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "AI_GATEWAY_API_KEYS",
+    "lbl": "AI Gateway pool (comma-sep)",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "COPILOT_GITHUB_TOKENS",
+    "lbl": "GitHub Copilot token pool",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "KIMI_API_KEYS",
+    "lbl": "Kimi pool (merged with MOONSHOT_API_KEYS into one rotation pool)",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "MODELSTUDIO_API_KEYS",
+    "lbl": "ModelStudio pool",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "QIANFAN_API_KEYS",
+    "lbl": "Qianfan pool",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "SYNTHETIC_API_KEYS",
+    "lbl": "Synthetic pool",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Rotation Pools",
+    "icon": "🔄",
+    "k": "VENICE_API_KEYS",
+    "lbl": "Venice pool",
+    "type": "text",
+    "tag": "advanced"
+  },
+  {
+    "g": "Model Lists",
+    "icon": "📋",
+    "k": "VENICE_MODELS",
+    "lbl": "Visible Venice models",
+    "type": "model_list",
+    "options_key": "VENICE_MODELS",
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
+  },
+  {
+    "g": "Model Lists",
+    "icon": "📋",
+    "k": "SYNTHETIC_MODELS",
+    "lbl": "Visible Synthetic models",
+    "type": "model_list",
+    "options_key": "SYNTHETIC_MODELS",
+    "ph": "Select models to build a comma list",
+    "tag": "optional"
   }
-];
+]
 
 const ICONS = {
-  All:'🏠', Core:'⚡', Deployment:'🧭', 'Provider Keys':'🔑', 'Rotation Pools':'🔄',
-  'Model Lists':'📋', 'Custom Provider':'🔌', Telegram:'✈️', WhatsApp:'💬',
-  Cloudflare:'☁️', Backup:'💾', DevData:'🧪', Runtime:'⚙️', 'Custom Env':'🔧'
+  All:'🏠', Core:'⚡', Startup:'🚀', DevData:'🧪', WhatsApp:'💬',
+  Cloudflare:'☁️', Gateway:'🔀', Logging:'📝', Network:'🌐', Plugins:'🔌',
+  Deployment:'🧭', 'Provider Keys':'🔑', 'Rotation Pools':'🔄',
+  'Model Lists':'📋', 'Custom Provider':'🧩', Telegram:'✈️',
+  Backup:'💾', Runtime:'⚙️', Integrations:'🔗', 'Custom Env':'🔧'
 };
-
 const $ = id => document.getElementById(id);
 const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({
   '&': '&amp;',
@@ -1815,6 +2043,7 @@ function defaultValueFor(field) {
 }
 
 function valueControlHTML(field) {
+  if (!field || !field.k) return '<span style="color:red">Invalid field</span>';
   const key = esc(field.k);
   const placeholder = esc(field.ph || field.lbl || '');
   const isSecret = !!field.secret;
@@ -1854,15 +2083,21 @@ function valueControlHTML(field) {
       ${control}
     </div>`;
 
-  return control;
 }
 
-function cardHTML(f) {
-  const badge = f.secret
-    ? '<span class="badge badge-s">secret</span>'
-    : '<span class="badge badge-f">safe</span>';
+function cardHTML(f, origIdx = 0) {
+  const TAG_META = {
+    critical:   { cls: 'badge-critical',   lbl: 'critical'   },
+    credential: { cls: 'badge-credential', lbl: 'credential' },
+    feature:    { cls: 'badge-feature',    lbl: 'feature'    },
+    optional:   { cls: 'badge-optional',   lbl: 'optional'   },
+    advanced:   { cls: 'badge-advanced',   lbl: 'advanced'   },
+    build:      { cls: 'badge-build',      lbl: 'build-time' },
+  };
+  const tm = TAG_META[f.tag] || TAG_META.optional;
+  const badge = `<span class="badge ${tm.cls}">${tm.lbl}</span>`;
 
-  return `<div class="env-card" data-row data-group="${esc(f.g)}" data-search="${esc((f.g + ' ' + f.k + ' ' + (f.lbl || '')).toLowerCase())}">
+  return `<div class="env-card" data-row data-orig-idx="${origIdx}" data-group="${esc(f.g)}" data-search="${esc((f.g + ' ' + f.k + ' ' + (f.lbl || '') + ' ' + (f.tag || '')).toLowerCase())}" data-tag="${esc(f.tag || 'optional')}">
     <div class="card-top">
       <input type="checkbox" class="card-check" data-check="${esc(f.k)}" ${f.common ? 'data-common="1"' : ''}>
       <div class="card-info">
@@ -1940,14 +2175,17 @@ function collect() {
   return obj;
 }
 
-function refresh() {
+function generateBundle() {
   const obj = collect();
   const keys = Object.keys(obj).sort();
   const bundle = keys.length ? encodeBundle(Object.fromEntries(keys.map(k => [k, obj[k]]))) : '';
-
   $('bundleOut').value = bundle;
   $('envLineOut').value = bundle ? `HUGGINGCLAW_ENV_BUNDLE=${bundle}` : '';
+}
 
+function refresh() {
+  const obj = collect();
+  const keys = Object.keys(obj).sort();
   const s = $('summary');
   if (keys.length) {
     s.innerHTML = `<strong>${keys.length}</strong> variable${keys.length > 1 ? 's' : ''} selected<div class="sum-keys">${keys.map(k => `<span class="sum-key">${esc(k)}</span>`).join('')}</div>`;
@@ -2036,7 +2274,7 @@ function applyObj(obj, replace = false) {
       addCustomRow(key, val, true);
     }
   }
-  markSelected(); filter(); refresh();
+  sortAllSections(); markSelected(); filter(); refresh();
 }
 
 function autoCheck(key) {
@@ -2125,13 +2363,34 @@ function toggleField(key) {
   const chk = document.querySelector(`[data-check="${CSS.escape(key)}"]`);
   if (chk) {
     chk.checked = on;
+    sortSection(inp.closest('[data-row]'));
     markSelected();
   }
   refresh();
 }
 
+function sortSection(cardEl) {
+  const cards = cardEl && cardEl.closest('.cards');
+  if (!cards) return;
+  const all     = [...cards.querySelectorAll('[data-row]')];
+  const checked = all.filter(c =>  c.querySelector('[data-check]')?.checked);
+  const rest    = all.filter(c => !c.querySelector('[data-check]')?.checked);
+  rest.sort((a, b) => Number(a.dataset.origIdx) - Number(b.dataset.origIdx));
+  [...checked, ...rest].forEach(c => cards.appendChild(c));
+}
+
+function sortAllSections() {
+  document.querySelectorAll('.cards').forEach(cards => {
+    const all     = [...cards.querySelectorAll('[data-row]')];
+    const checked = all.filter(c =>  c.querySelector('[data-check]')?.checked);
+    const rest    = all.filter(c => !c.querySelector('[data-check]')?.checked);
+    rest.sort((a, b) => Number(a.dataset.origIdx) - Number(b.dataset.origIdx));
+    [...checked, ...rest].forEach(c => cards.appendChild(c));
+  });
+}
+
 function bindFieldEvents() {
-  document.querySelectorAll('[data-check]').forEach(el => el.addEventListener('change', () => { markSelected(); refresh(); }));
+  document.querySelectorAll('[data-check]').forEach(el => el.addEventListener('change', () => { sortSection(el.closest('[data-row]')); markSelected(); refresh(); }));
   document.querySelectorAll('[data-key]').forEach(el => el.addEventListener('input', refresh));
   document.querySelectorAll('[data-toggle]').forEach(btn => btn.addEventListener('click', () => toggleField(btn.dataset.toggle)));
   document.querySelectorAll('[data-pick-for]').forEach(sel => sel.addEventListener('change', () => handlePickerChange(sel)));
@@ -2141,22 +2400,31 @@ function bindFieldEvents() {
 
 function renderSections() {
   const grouped = {};
-  FIELDS.forEach(f => { (grouped[f.g] ||= []).push(f); });
+  FIELDS.forEach(f => {
+    if (!f || !f.g || !f.k) return;
+    (grouped[f.g] ||= []).push(f);
+  });
 
   const wrap = $('sections');
+  if (!wrap) return;
   wrap.innerHTML = '';
   Object.entries(grouped).forEach(([grp, items]) => {
-    const sec = document.createElement('div');
-    sec.className = 'sec';
-    sec.dataset.section = grp;
-    sec.innerHTML = `
-      <div class="sec-header">
-        <span class="sec-icon">${ICONS[grp] || '📁'}</span>
-        <span class="sec-title">${esc(grp)}</span>
-        <div class="sec-line"></div>
-      </div>
-      <div class="cards">${items.map(cardHTML).join('')}</div>`;
-    wrap.appendChild(sec);
+    try {
+      const sec = document.createElement('div');
+      sec.className = 'sec';
+      sec.dataset.section = grp;
+      sec.innerHTML = `
+        <div class="sec-header">
+          <span class="sec-icon">${ICONS[grp] || '📁'}</span>
+          <span class="sec-title">${esc(grp)}</span>
+          <span class="sec-count">${items.length}</span>
+          <div class="sec-line"></div>
+        </div>
+        <div class="cards">${items.map((f, i) => { try { return cardHTML(f, i); } catch(e) { console.error('cardHTML error for field', f.k, e); return ''; } }).join('')}</div>`;
+      wrap.appendChild(sec);
+    } catch(e) {
+      console.error('renderSections error for group', grp, e);
+    }
   });
   bindFieldEvents();
 }
@@ -2179,66 +2447,62 @@ function copyText(text) {
 }
 
 // ── Init ──
-renderSidebar();
-renderSections();
-addCustomRow();
-filter();
-refresh();
+try {
+  renderSidebar();
+  renderSections();
+  addCustomRow();
+  filter();
+  refresh();
+} catch(e) {
+  console.error('HuggingClaw ENV Builder init error:', e);
+  const wrap = document.getElementById('sections');
+  if (wrap) wrap.innerHTML = '<div style="color:red;padding:20px">ENV Builder failed to load. Open browser console for details. Error: ' + e.message + '</div>';
+}
 
 // ── Events ──
 $('search').oninput = filter;
+$('selectRequired').onclick = () => {
+  document.querySelectorAll('[data-row][data-tag="critical"] [data-check]').forEach(c => c.checked = true);
+  sortAllSections();
+  markSelected();
+  refresh();
+};
 $('selectCommon').onclick = () => {
   document.querySelectorAll('[data-common="1"]').forEach(c => c.checked = true);
+  sortAllSections();
   markSelected();
   refresh();
 };
 $('selectVisible').onclick = () => {
   document.querySelectorAll('.sec:not(.sec-hidden) [data-row]:not(.hidden) [data-check]').forEach(c => c.checked = true);
+  sortAllSections();
   markSelected();
   refresh();
 };
 $('clearAll').onclick = () => {
   clearForm();
+  sortAllSections();
   markSelected();
   filter();
   refresh();
 };
 $('applyImport').onclick = () => {
   try {
-    applyObj(parseEnv($('importText').value), true);
-    showToast('Imported ✓');
+    const parsed = parseEnv($('importText').value);
+    const count = Object.keys(parsed).length;
+    if (!count) {
+      showToast('No valid env keys found');
+      return;
+    }
+    applyObj(parsed, true);
+    showToast(`Imported ${count} key${count > 1 ? 's' : ''} ✓`);
   } catch (e) {
     showToast('Import failed');
     alert(e.message);
   }
 };
 
-// Auto-import: paste karo aur turant parse + apply ho jaata hai
-$('importText').addEventListener('paste', () => {
-  setTimeout(() => {
-    try {
-      const val = $('importText').value.trim();
-      if (!val) return;
-      applyObj(parseEnv(val), true);
-      showToast('Auto-imported ✓');
-    } catch (e) {
-      showToast('Import failed');
-    }
-  }, 0);
-});
-
-// Live typing: jaise jaise type karo env format mein, bundle banta jaata hai
-$('importText').addEventListener('input', () => {
-  const val = $('importText').value.trim();
-  if (!val) return;
-  // Sirf agar valid env/bundle format lag raha ho tabhi auto-apply
-  const looksLikeEnv = val.includes('=') || val.startsWith('{') || /^[A-Za-z0-9_\-]{20,}$/.test(val);
-  if (looksLikeEnv) {
-    try {
-      applyObj(parseEnv(val), true);
-    } catch (e) { /* silent — user abhi type kar raha hai */ }
-  }
-});
+// Import is explicit via the Import & Apply button to avoid surprising UI resets.
 $('addCustom').onclick = () => addCustomRow();
 $('applyBundle').onclick = () => {
   try {
@@ -2248,6 +2512,7 @@ $('applyBundle').onclick = () => {
     showToast('Invalid bundle');
   }
 };
+$('generateBundle').onclick = () => generateBundle();
 $('copyBundle').onclick = () => copyText($('bundleOut').value);
 $('copyEnvLine').onclick = () => copyText($('envLineOut').value);
 $('copyJson').onclick = () => copyText(JSON.stringify(collect(), null, 2));

health-server.js

@@ -25,10 +25,15 @@ const GATEWAY_TOKEN = (process.env.GATEWAY_TOKEN || "").trim();
 const SESSION_COOKIE = "hc_session";
 const LOGIN_PATH = "/login";
 const DEV_MODE_ENABLED = isTrue(process.env.DEV_MODE);
-// Default true. Only false when DEV_MODE=false or HUGGINGCLAW_JUPYTER_ENABLED=false is explicitly set.
+// Explicit HUGGINGCLAW_JUPYTER_ENABLED=true enables Jupyter.
+// Otherwise DEV_MODE=true enables it unless HUGGINGCLAW_JUPYTER_ENABLED is explicitly false.
+// HUGGINGCLAW_JUPYTER_ENABLED=true is the explicit user override and always wins.
 const JUPYTER_ENABLED =
-  !/^(false|0|no|off)$/i.test(String(process.env.DEV_MODE || "").trim()) &&
-  !/^(false|0|no|off)$/i.test(String(process.env.HUGGINGCLAW_JUPYTER_ENABLED || "").trim());
+  /^(true|1|yes|on)$/i.test(String(process.env.HUGGINGCLAW_JUPYTER_ENABLED || "").trim()) ||
+  (
+    isTrue(process.env.DEV_MODE) &&
+    !/^(false|0|no|off)$/i.test(String(process.env.HUGGINGCLAW_JUPYTER_ENABLED || "").trim())
+  );
 const startTime = Date.now();
 const LLM_MODEL = process.env.LLM_MODEL || "Not Set";
 const LLM_PROVIDER = LLM_MODEL.includes("/") ? LLM_MODEL.split("/")[0] : "";
@@ -60,50 +65,134 @@ function deriveHfSpaceUrl() {
   return "";
 }
 const HF_SPACE_URL = deriveHfSpaceUrl();
+const _privacyWaitRaw = Number(process.env.PRIVACY_DETECTION_WAIT_MS || "1500");
+const PRIVACY_DETECTION_WAIT_MS = Number.isFinite(_privacyWaitRaw)
+  ? Math.max(0, Math.floor(_privacyWaitRaw))
+  : 1500;
+
+// ── Privacy Detection ──
+// Priority order:
+//   1. SPACE_PRIVACY env var ("public" / "private") — explicit user override, most reliable
+//   2. HF API call to huggingface.co — auto-detect
+//   3. Fail-secure default: treat as private if SPACE_ID is set
+
+// 1. Check explicit env var override first
+const _spacPrivacyEnv = (process.env.SPACE_PRIVACY || "").trim().toLowerCase();
+let SPACE_IS_PRIVATE;
+let _privacyDetectionDone = false;
+let _privacyDetectionResolve;
+const privacyDetectionReady = new Promise((res) => { _privacyDetectionResolve = res; });
+
+if (_spacPrivacyEnv === "public") {
+  // User explicitly set SPACE_PRIVACY=public — skip API call entirely
+  SPACE_IS_PRIVATE = false;
+  _privacyDetectionDone = true;
+  console.log("[health-server] Space privacy: public (SPACE_PRIVACY env var override)");
+  _privacyDetectionResolve && _privacyDetectionResolve();
+} else if (_spacPrivacyEnv === "private") {
+  // User explicitly set SPACE_PRIVACY=private — skip API call entirely
+  SPACE_IS_PRIVATE = true;
+  _privacyDetectionDone = true;
+  console.log("[health-server] Space privacy: private (SPACE_PRIVACY env var override)");
+  _privacyDetectionResolve && _privacyDetectionResolve();
+} else {
+  // 2. Auto-detect via HF API (with fail-secure default)
+  // Default to private if SPACE_ID is set — gets corrected by API call below.
+  SPACE_IS_PRIVATE = !!SPACE_ID;
+}
 
-// Auto-detect space privacy via HF API at startup.
-// Caches result so every request doesn't hit the API.
-let SPACE_IS_PRIVATE = false;
 async function detectSpacePrivacy() {
-  if (!SPACE_ID) return;
-  try {
-    const token = (process.env.HF_TOKEN || "").trim();
-    const reqOptions = {
-      hostname: "huggingface.co",
-      path: `/api/spaces/${SPACE_ID}`,
-      method: "GET",
-      headers: Object.assign(
-        { "User-Agent": "HuggingClaw/health-server" },
-        token ? { Authorization: `Bearer ${token}` } : {}
-      ),
-    };
-    await new Promise((resolve) => {
-      const r = https.request(reqOptions, (res) => {
-        let body = "";
-        res.on("data", (chunk) => { body += chunk; });
-        res.on("end", () => {
-          try {
-            if (res.statusCode === 200) {
-              const data = JSON.parse(body);
-              SPACE_IS_PRIVATE = data.private === true;
-            } else if (res.statusCode === 404 && !token) {
-              // 404 with no token usually means private space
-              SPACE_IS_PRIVATE = true;
-            }
-          } catch {}
-          resolve();
+  // Skip if already resolved via env var
+  if (_spacPrivacyEnv === "public" || _spacPrivacyEnv === "private") return;
+  // Skip if not running on HF Spaces
+  if (!SPACE_ID) {
+    SPACE_IS_PRIVATE = false;
+    _privacyDetectionDone = true;
+    _privacyDetectionResolve();
+    return;
+  }
+
+  const token = (process.env.HF_TOKEN || process.env.HUGGINGFACE_HUB_TOKEN || "").trim();
+  const reqOptions = {
+    hostname: "huggingface.co",
+    path: `/api/spaces/${SPACE_ID}`,
+    method: "GET",
+    headers: Object.assign(
+      { "User-Agent": "HuggingClaw/health-server" },
+      token ? { Authorization: `Bearer ${token}` } : {}
+    ),
+  };
+
+  // Retry up to 5 times with increasing delay — covers transient failures at boot
+  const MAX_ATTEMPTS = 5;
+  let detected = false;
+
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      const result = await new Promise((resolve) => {
+        const r = https.request(reqOptions, (apiRes) => {
+          let body = "";
+          apiRes.on("data", (chunk) => { body += chunk; });
+          apiRes.on("end", () => {
+            try {
+              if (apiRes.statusCode === 200) {
+                const data = JSON.parse(body);
+                // API confirmed privacy status
+                SPACE_IS_PRIVATE = data.private === true;
+                resolve({ ok: true, status: apiRes.statusCode });
+              } else if (apiRes.statusCode === 401 || apiRes.statusCode === 403) {
+                // 401/403 on /api/spaces means the space IS private and our token
+                // is missing or wrong. Mark as private.
+                SPACE_IS_PRIVATE = true;
+                resolve({ ok: true, status: apiRes.statusCode, forcedPrivate: true });
+              } else if (apiRes.statusCode === 404) {
+                // Space not found — shouldn't happen but treat as non-blocking; default stays.
+                resolve({ ok: false, status: apiRes.statusCode });
+              } else {
+                // Other non-200 — transient; retry
+                resolve({ ok: false, status: apiRes.statusCode });
+              }
+            } catch { resolve({ ok: false, status: apiRes.statusCode }); }
+          });
         });
+        r.on("error", (err) => resolve({ ok: false, error: err.message }));
+        r.setTimeout(8000, () => { r.destroy(); resolve({ ok: false, error: "timeout" }); });
+        r.end();
       });
-      r.on("error", resolve);
-      r.setTimeout(5000, () => { r.destroy(); resolve(); });
-      r.end();
-    });
-    console.log(`[health-server] Space privacy detected: ${SPACE_IS_PRIVATE ? "private" : "public"}`);
-  } catch {
-    // Network error — default to false (safe)
+
+      console.log(`[health-server] Privacy detection attempt ${attempt}/${MAX_ATTEMPTS}: status=${result.status || "network-error"} ok=${result.ok}`);
+
+      if (result.ok) { detected = true; break; }
+    } catch (err) {
+      console.warn(`[health-server] Privacy detection attempt ${attempt} threw: ${err.message}`);
+    }
+
+    const delay = Math.min(2000 * attempt, 10000); // 2s, 4s, 6s, 8s, 10s
+    if (attempt < MAX_ATTEMPTS) {
+      await new Promise((r) => setTimeout(r, delay));
+    }
+  }
+
+  if (!detected) {
+    console.warn(
+      `[health-server] Privacy detection failed after ${MAX_ATTEMPTS} attempts — ` +
+      `defaulting to ${SPACE_IS_PRIVATE ? "private" : "public"}. ` +
+      `TIP: Set SPACE_PRIVACY=public (or private) in your Space secrets to skip API detection.`
+    );
+  } else {
+    console.log(`[health-server] Space privacy detected via HF API: ${SPACE_IS_PRIVATE ? "private" : "public"}`);
   }
+
+  _privacyDetectionDone = true;
+  _privacyDetectionResolve();
+}
+
+// Only run API detection if env var override not used
+if (_spacPrivacyEnv !== "public" && _spacPrivacyEnv !== "private") {
+  detectSpacePrivacy();
+  // Re-check every 5 minutes so runtime public↔private changes are picked up
+  setInterval(detectSpacePrivacy, 5 * 60 * 1000);
 }
-detectSpacePrivacy();
 const CLOUDFLARE_KEEPALIVE_STATUS_FILE =
   "/tmp/huggingclaw-cloudflare-keepalive-status.json";
 
@@ -349,15 +438,63 @@ function renderDashboard(data) {
     <a class="hero-action env" data-space-link="env-builder" href="/env-builder">⚙️ Env Builder →</a>
   </div>
   <section class="overview">${tilesHtml}</section>
-  <footer>Built by <a href="https://github.com/somratpro" target="_blank" rel="noopener noreferrer" style="color:inherit;text-decoration:none">@somratpro</a>${JUPYTER_ENABLED ? " · Terminal by JupyterLab" : ""}</footer>
+  <footer>Built by <a href="https://github.com/somratpro" target="_blank" rel="noopener noreferrer" style="color:inherit;text-decoration:none">@somratpro</a>${JUPYTER_ENABLED ? " · Terminal by JupyterLab" : ""}<br>Env Builder &amp; JupyterLab integration by<br><a href="https://github.com/anurag008w" target="_blank" rel="noopener noreferrer" style="color:inherit;text-decoration:none">@anurag</a></footer>
   </main>
   <script>
   document.querySelectorAll('.local-time').forEach(el=>{const d=new Date(el.getAttribute('data-iso'));if(!isNaN(d))el.textContent='At '+d.toLocaleTimeString()});
   const inEmbeddedApp = (() => { try { return window.top !== window.self; } catch { return true; } })();
   const isDirectHfSpaceHost = /\.hf\.space$/i.test(window.location.hostname);
   const HF_SPACE_URL = ${JSON.stringify(HF_SPACE_URL)};
-  const SPACE_IS_PRIVATE = ${JSON.stringify(SPACE_IS_PRIVATE)};
-  // ── Private Space Guard ──
+  // Server-side detected value (may be stale if page was cached — see /api/is-private)
+  let SPACE_IS_PRIVATE = ${JSON.stringify(SPACE_IS_PRIVATE)};
+
+  function applyLinkTargets() {
+    // Keep hero buttons in-frame for private spaces; open new tab for public spaces
+    // accessed via the HF iframe or directly at .hf.space.
+    const openInNewTab = !SPACE_IS_PRIVATE && (inEmbeddedApp || isDirectHfSpaceHost);
+    document.querySelectorAll('a[data-space-link]').forEach((a) => {
+      if (openInNewTab) {
+        a.setAttribute('target', '_blank');
+        a.setAttribute('rel', 'noopener noreferrer');
+      } else {
+        a.removeAttribute('target');
+        a.removeAttribute('rel');
+      }
+    });
+  }
+
+  applyLinkTargets();
+
+  // Always re-fetch the live privacy status from the server to handle:
+  // 1. Startup race condition where server rendered before API detection finished
+  // 2. Any mismatch between client-rendered value and actual server-side state
+  // 3. Public spaces where the fail-secure default (private) needs correcting
+  // Also retries after 4s in case the first fetch raced with a server-side retry.
+  function syncPrivacy() {
+    return fetch('/api/is-private', { cache: 'no-store' })
+      .then(r => r.json())
+      .then(d => {
+        if (d.isPrivate !== SPACE_IS_PRIVATE) {
+          SPACE_IS_PRIVATE = d.isPrivate;
+          applyLinkTargets(); // re-run: adds or removes target="_blank" on buttons
+        }
+        return d.isPrivate;
+      })
+      .catch(() => SPACE_IS_PRIVATE);
+  }
+
+  if (isDirectHfSpaceHost) {
+    // Immediate check on page load
+    syncPrivacy().then(isPrivate => {
+      // If space appears private after first check, re-verify after server retries
+      // complete (server retries up to 3×5s = ~15s). This catches the edge case
+      // where a PUBLIC space returned private due to a transient API failure.
+      if (isPrivate) {
+        setTimeout(syncPrivacy, 8000);
+        setTimeout(syncPrivacy, 16000);
+      }
+    });
+  }
   // Direct .hf.space access outside the HF App iframe has no valid session cookie
   // for private spaces — HF CDN returns 404 before the request reaches the container.
   // Redirect users to huggingface.co/spaces/... which authenticates them properly.
@@ -368,18 +505,6 @@ function renderDashboard(data) {
     document.body.appendChild(notice);
     setTimeout(() => { window.location.replace(HF_SPACE_URL); }, 300);
   }
-  // If inside the HF App iframe, force new-tab navigation so users can break out
-  // to the standalone Space host. Also keep direct .hf.space behavior opening new tabs.
-  const openInNewTab = inEmbeddedApp || isDirectHfSpaceHost;
-  document.querySelectorAll('a[data-space-link]').forEach((a) => {
-    if (openInNewTab) {
-      a.setAttribute('target', '_blank');
-      a.setAttribute('rel', 'noopener noreferrer');
-    } else {
-      a.removeAttribute('target');
-      a.removeAttribute('rel');
-    }
-  });
 </script>
 </body></html>`;
 }
@@ -388,7 +513,6 @@ function renderPrivateRedirect(targetUrl) {
   const safeUrl = escapeHtml(targetUrl);
   return `<!doctype html><html lang="en"><head>
   <meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
-  <meta http-equiv="refresh" content="3;url=${safeUrl}"/>
   <title>HuggingClaw — Private Space</title>
   <style>
     :root{color-scheme:dark}
@@ -411,8 +535,13 @@ function renderPrivateRedirect(targetUrl) {
     <div class="sub">Redirecting in 3 seconds&hellip;</div>
   </div>
   <script>
-    // Immediate redirect if JS available — don't wait for meta refresh
-    setTimeout(() => { window.location.replace(${JSON.stringify(targetUrl)}); }, 100);
+    // Only auto-redirect when NOT inside an iframe (e.g. HF App tab embeds this
+    // page in an iframe; navigating that iframe to huggingface.co is blocked by
+    // X-Frame-Options and causes "refused to connect" in the browser).
+    const _inFrame = (() => { try { return window.top !== window.self; } catch { return true; } })();
+    if (!_inFrame) {
+      setTimeout(() => { window.location.replace(${JSON.stringify(targetUrl)}); }, 100);
+    }
   </script>
 </body></html>`;
 }
@@ -513,6 +642,15 @@ function proxyHTTP(req, res, targetHost, targetPort, options = {}) {
 const server = http.createServer(async (req, res) => {
   const { pathname } = parseRequestUrl(req.url);
 
+  // Lightweight endpoint for client-side fallback detection.
+  // Called by the dashboard JS if it suspects the server-rendered SPACE_IS_PRIVATE
+  // value was stale (race condition at startup). No auth required — it's not sensitive.
+  if (pathname === "/api/is-private") {
+    if (!_privacyDetectionDone) await privacyDetectionReady;
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    return res.end(JSON.stringify({ isPrivate: SPACE_IS_PRIVATE }));
+  }
+
   if (pathname === "/health") {
     const gatewayReady = await probePort(GATEWAY_HOST, GATEWAY_PORT, "/health");
     res.writeHead(gatewayReady ? 200 : 503, { "Content-Type": "application/json" });
@@ -545,11 +683,45 @@ const server = http.createServer(async (req, res) => {
   // and WebSocket upgrades pass through untouched.
   // /health and /status are always exempt so uptime monitors keep working.
   const isHtmlRequest = (req.headers.accept || "").includes("text/html");
+
+  // RACE CONDITION FIX: Wait for privacy detection to finish BEFORE computing
+  // isDirectHfSpaceRequest. Previously this const was computed immediately with
+  // the fail-secure default (SPACE_IS_PRIVATE=true), causing private redirects
+  // even when the space is actually public or the owner is accessing via HF App.
+  // After the very first HTML request, _privacyDetectionDone=true so no delay.
+  let privacyWaitTimedOut = false;
+  if (isHtmlRequest && !_privacyDetectionDone) {
+    const waitResult = await Promise.race([
+      privacyDetectionReady.then(() => "detected"),
+      new Promise((resolve) => setTimeout(() => resolve("timeout"), PRIVACY_DETECTION_WAIT_MS)),
+    ]);
+    privacyWaitTimedOut = waitResult == "timeout";
+  }
+
+  // In-app navigation (clicking links within the HF iframe) sends a Referer
+  // from the same .hf.space origin — don't redirect those, only redirect
+  // fresh direct browser access that has no same-origin referer.
+  const referer = req.headers.referer || req.headers.referrer || "";
+  const isSameOriginNav = !!(referer && typeof req.headers.host === "string" &&
+    referer.startsWith(`https://${req.headers.host}`));
+  // When HF App embeds the space in an iframe, the initial request has
+  // Referer: https://huggingface.co/spaces/... (NOT .hf.space).
+  // HF handles authentication itself — if the user is not logged in, HF
+  // redirects them before the iframe ever loads. So a huggingface.co referer
+  // means the user is already authenticated; skip the private redirect.
+  const isFromHFApp = !!(referer && (
+    referer.startsWith("https://huggingface.co") ||
+    referer.startsWith("https://hf.co")
+  ));
+  // NOTE: computed AFTER detection is awaited above — always uses real value.
   const isDirectHfSpaceRequest = SPACE_IS_PRIVATE &&
+    !privacyWaitTimedOut &&
     HF_SPACE_URL &&
     isHtmlRequest &&
     typeof req.headers.host === "string" &&
-    req.headers.host.endsWith(".hf.space");
+    req.headers.host.endsWith(".hf.space") &&
+    !isSameOriginNav &&
+    !isFromHFApp;
 
   if (pathname === LOGIN_PATH) {
     if (isAuthorized(req)) {
@@ -587,7 +759,7 @@ const server = http.createServer(async (req, res) => {
 
   if (pathname === "/env-builder" || pathname === "/env-builder/") {
     if (isDirectHfSpaceRequest) {
-      res.writeHead(200, { "Content-Type": "text/html" });
+      res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-store" });
       return res.end(renderPrivateRedirect(HF_SPACE_URL));
     }
     if (!requireAuth(req, res)) return;
@@ -599,7 +771,7 @@ const server = http.createServer(async (req, res) => {
     if (!requireAuth(req, res)) return;
     try {
       const js = fs.readFileSync(require("path").join(__dirname, "env-builder.js"), "utf8");
-      res.writeHead(200, { "Content-Type": "application/javascript" });
+      res.writeHead(200, { "Content-Type": "application/javascript", "Cache-Control": "no-store" });
       return res.end(js);
     } catch (exc) {
       res.writeHead(404, { "Content-Type": "text/plain" });
@@ -608,6 +780,7 @@ const server = http.createServer(async (req, res) => {
   }
 
   if (pathname === "/" || pathname === "/dashboard") {
+    // Detection already awaited above (in the isHtmlRequest guard) — no extra wait needed.
     if (isDirectHfSpaceRequest) {
       res.writeHead(200, { "Content-Type": "text/html" });
       return res.end(renderPrivateRedirect(HF_SPACE_URL));

iframe-fix.cjs

@@ -19,9 +19,10 @@ http.Server.prototype.emit = function (event, ...args) {
   if (event === "request") {
     const [, res] = args;
 
-    // Only intercept on the main OpenClaw server (port 7860)
+    // Only intercept on the main OpenClaw server (respects GATEWAY_PORT env var)
+    const expectedPort = Number(process.env.GATEWAY_PORT || 7860);
     const serverPort = this.address && this.address() && this.address().port;
-    if (serverPort && serverPort !== 7860) {
+    if (serverPort && serverPort !== expectedPort) {
       return origEmit.apply(this, [event, ...args]);
     }
 

jupyter-devdata-sync.py

@@ -61,7 +61,11 @@ EXCLUDE = {
 
 
 def enabled():
-    dev = is_true(os.environ.get("DEV_MODE", ""))
+    jupyter_override = os.environ.get("HUGGINGCLAW_JUPYTER_ENABLED", "")
+    if jupyter_override.strip():
+        dev = is_true(jupyter_override)
+    else:
+        dev = is_true(os.environ.get("DEV_MODE", ""))
     separate_dataset = DATASET_NAME != BACKUP_DATASET_NAME
     if ENABLE and dev and HF_TOKEN and not separate_dataset:
         print("DevData sync disabled: DEVDATA_DATASET_NAME must be separate from BACKUP_DATASET_NAME.")
@@ -97,22 +101,41 @@ import fnmatch as _fnmatch
 SECRET_FILENAME_PATTERNS = {
     ".env",           # dotenv files — almost always contain API keys
     ".env.*",         # .env.local, .env.production, etc.
-    "*secret*",       # any file/dir whose name contains "secret"
-    "*secrets*",
-    "*_secret*",
-    "*-secret*",
-    "*key*",          # private keys, API key files
-    "*_key*",
-    "*-key*",
-    "*token*",        # token files
-    "*_token*",
-    "*-token*",
+    "id_rsa",
+    "id_dsa",
+    "id_ecdsa",
+    "id_ed25519",
+    "authorized_keys",
+    "known_hosts",
+    "secret",
+    "secrets",
+    "secret.*",
+    "*.secret",
+    "*_secret",
+    "*_secret.*",
+    "*-secret",
+    "*-secret.*",
+    "token",
+    "token.*",
+    "*.token",
+    "*_token",
+    "*_token.*",
+    "*-token",
+    "*-token.*",
+    "api_token",
+    "access_token",
+    "refresh_token",
+    "credentials",    # common credential file names
+    "credentials.*",
+    "auth.json",
+    "auth.yaml",
+    "auth.yml",
+    "auth.toml",
+    "auth.ini",
     "*.pem",          # TLS/SSH private keys
     "*.key",          # generic key files
     "*.p12",          # PKCS#12 bundles
     "*.pfx",
-    "credentials",    # common credential file names
-    "credentials.*",
     ".netrc",         # stores plaintext passwords
     ".htpasswd",
 }
@@ -174,6 +197,7 @@ def is_jupyter_running(port: int = 8888) -> bool:
         return False
 
 def restore_once(api, rid: str):
+    from huggingface_hub import snapshot_download
     from huggingface_hub.errors import RepositoryNotFoundError
     tmp = Path(tempfile.mkdtemp(prefix="devdata-restore-"))
     try:

multi-provider-key-rotator.cjs

@@ -3,266 +3,248 @@
 /**
  * Multi-provider API key rotator for OpenClaw/HuggingClaw
  * --------------------------------------------------------
- * Works exactly like nvidia-key-rotator.cjs but covers every
- * provider that HuggingClaw supports.
+ * - Round-robin rotation per provider
+ * - 429/402 → exponential backoff blacklist per key
+ * - After MAX_STRIKES consecutive failures → permanent session blacklist
+ * - Successful response → strikes reset
+ * - 10+ keys handled correctly (idx tracks only active keys, no drift)
  *
- * For each provider you can supply a comma-separated pool:
- *   ANTHROPIC_API_KEYS=key1,key2,key3
- * Falls back to the singular env var, and optionally to LLM_API_KEY.
- *
- * Keys are rotated round-robin per provider independently.
- *
- * Patches globalThis.fetch + node:http + node:https so that
- * virtually every caller is covered without code changes.
+ * Env vars:
+ *   KEY_BLACKLIST_COOLDOWN_MS   base backoff ms        (default 60 000)
+ *   KEY_MAX_STRIKES             failures before perm   (default 3)
+ *   LLM_API_KEY_FALLBACK_ENABLED true/false            (default true)
  */
 
 const http  = require('node:http');
 const https = require('node:https');
 
-// This file is preloaded through NODE_OPTIONS, so it also runs inside npm and
-// OpenClaw helper subprocesses that may emit machine-readable JSON on stdout.
-// Keep rotator diagnostics on stderr to avoid corrupting those stdout streams.
-const log = (...args) => console.error(...args);
+const log  = (...a) => console.error(...a);
+const warn = (...a) => console.warn(...a);
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const BASE_COOLDOWN_MS = Math.max(
+  1000,
+  parseInt(process.env.KEY_BLACKLIST_COOLDOWN_MS || '', 10) || 60_000,
+);
+const MAX_STRIKES = Math.max(
+  1,
+  parseInt(process.env.KEY_MAX_STRIKES || '', 10) || 3,
+);
+// Permanently blacklisted keys retry after this long (default 24 h).
+// "Permanent" just means very long — avoids truly forever loops on app restart.
+const PERM_BLACKLIST_MS = 24 * 60 * 60 * 1000;
 
 // ─── Provider definitions ────────────────────────────────────────────────────
-//
-// hostname  – regex tested against the request hostname (case-insensitive)
-// envPlural – env var that holds a comma-separated key pool  (preferred)
-// envSingular – env var that holds a single key              (fallback)
-//
-// LLM_API_KEY fallback can be controlled via:
-//   LLM_API_KEY_FALLBACK_ENABLED=true|false
-// Default is enabled for backwards compatibility.
-//
-const PROVIDERS = [
-  {
-    name:       'anthropic',
-    hostname:   /(?:^|\.)api\.anthropic\.com$/i,
-    envPlural:  'ANTHROPIC_API_KEYS',
-    envSingular:'ANTHROPIC_API_KEY',
-  },
-  {
-    name:       'openai',
-    hostname:   /(?:^|\.)api\.openai\.com$/i,
-    envPlural:  'OPENAI_API_KEYS',
-    envSingular:'OPENAI_API_KEY',
-  },
-  {
-    name:       'gemini',
-    // Gemini uses generativelanguage API; also covers aiplatform
-    hostname:   /(?:^|\.)(?:generativelanguage\.googleapis\.com|aiplatform\.googleapis\.com)$/i,
-    envPlural:  'GEMINI_API_KEYS',
-    envSingular:'GEMINI_API_KEY',
-    queryParam: true,
-  },
-  {
-    name:       'deepseek',
-    hostname:   /(?:^|\.)api\.deepseek\.com$/i,
-    envPlural:  'DEEPSEEK_API_KEYS',
-    envSingular:'DEEPSEEK_API_KEY',
-  },
-  {
-    name:       'openrouter',
-    hostname:   /(?:^|\.)openrouter\.ai$/i,
-    envPlural:  'OPENROUTER_API_KEYS',
-    envSingular:'OPENROUTER_API_KEY',
-  },
-  {
-    name:       'kilocode',
-    hostname:   /(?:^|\.)kilocode\.ai$/i,
-    envPlural:  'KILOCODE_API_KEYS',
-    envSingular:'KILOCODE_API_KEY',
-  },
-  {
-    name:       'opencode',
-    hostname:   /(?:^|\.)opencode\.ai$/i,
-    envPlural:  'OPENCODE_API_KEYS',
-    envSingular:'OPENCODE_API_KEY',
-  },
-  {
-    name:       'zai',
-    // Z.ai / GLM — both domains normalised to "zai" in OpenClaw
-    hostname:   /(?:^|\.)(?:z\.ai|open\.bigmodel\.cn)$/i,
-    envPlural:  'ZAI_API_KEYS',
-    envSingular:'ZAI_API_KEY',
-  },
-  {
-    name:       'moonshot',
-    hostname:   /(?:^|\.)api\.moonshot\.cn$/i,
-    envPlural:  'MOONSHOT_API_KEYS',
-    envSingular:'MOONSHOT_API_KEY',
-  },
-  {
-    name:       'minimax',
-    hostname:   /(?:^|\.)api\.minimax\.chat$/i,
-    envPlural:  'MINIMAX_API_KEYS',
-    envSingular:'MINIMAX_API_KEY',
-  },
-  {
-    name:       'xiaomi',
-    // MiMo — update hostname if Xiaomi publishes an official domain
-    hostname:   /(?:^|\.)api\.xiaomi\.com$/i,
-    envPlural:  'XIAOMI_API_KEYS',
-    envSingular:'XIAOMI_API_KEY',
-  },
-  {
-    name:       'volcengine',
-    // Volcengine / Doubao
-    hostname:   /(?:^|\.)(?:ark\.cn-beijing\.volces\.com|volcengineapi\.com)$/i,
-    envPlural:  'VOLCANO_ENGINE_API_KEYS',
-    envSingular:'VOLCANO_ENGINE_API_KEY',
-  },
-  {
-    name:       'byteplus',
-    hostname:   /(?:^|\.)maas-api\.ml-platform-cn-beijing\.byteplus\.com$/i,
-    envPlural:  'BYTEPLUS_API_KEYS',
-    envSingular:'BYTEPLUS_API_KEY',
-  },
-  {
-    name:       'mistral',
-    hostname:   /(?:^|\.)api\.mistral\.ai$/i,
-    envPlural:  'MISTRAL_API_KEYS',
-    envSingular:'MISTRAL_API_KEY',
-  },
-  {
-    name:       'xai',
-    hostname:   /(?:^|\.)api\.x\.ai$/i,
-    envPlural:  'XAI_API_KEYS',
-    envSingular:'XAI_API_KEY',
-  },
-  {
-    name:       'nvidia',
-    hostname:   /(?:^|\.)(?:integrate\.api\.nvidia\.com|api\.nvidia\.com)$/i,
-    envPlural:  'NVIDIA_API_KEYS',
-    envSingular:'NVIDIA_API_KEY',
-  },
-  {
-    name:       'groq',
-    hostname:   /(?:^|\.)api\.groq\.com$/i,
-    envPlural:  'GROQ_API_KEYS',
-    envSingular:'GROQ_API_KEY',
-  },
-  {
-    name:       'cohere',
-    hostname:   /(?:^|\.)api\.cohere\.(?:ai|com)$/i,
-    envPlural:  'COHERE_API_KEYS',
-    envSingular:'COHERE_API_KEY',
-  },
-  {
-    name:       'together',
-    hostname:   /(?:^|\.)api\.together\.(?:xyz|ai)$/i,
-    envPlural:  'TOGETHER_API_KEYS',
-    envSingular:'TOGETHER_API_KEY',
-  },
-  {
-    name:       'cerebras',
-    hostname:   /(?:^|\.)api\.cerebras\.ai$/i,
-    envPlural:  'CEREBRAS_API_KEYS',
-    envSingular:'CEREBRAS_API_KEY',
-  },
-  {
-    name:       'huggingface',
-    hostname:   /(?:^|\.)(?:api-inference\.huggingface\.co|router\.huggingface\.co|huggingface\.co)$/i,
-    envPlural:  'HUGGINGFACE_HUB_TOKENS',       // plural variant
-    envSingular:'HUGGINGFACE_HUB_TOKEN',
-  },
-  {
-    name:       'venice',
-    hostname:   /(?:^|\.)api\.venice\.ai$/i,
-    envPlural:  'VENICE_API_KEYS',
-    envSingular:'VENICE_API_KEY',
-  },
-  {
-    name:       'github-copilot',
-    hostname:   /(?:^|\.)api\.githubcopilot\.com$/i,
-    envPlural:  'COPILOT_GITHUB_TOKENS',
-    envSingular:'COPILOT_GITHUB_TOKEN',
-  },
-  {
-    name:       'qianfan',
-    // Baidu Qianfan / ERNIE
-    hostname:   /(?:^|\.)(?:aip|qianfan)\.baidubce\.com$/i,
-    envPlural:  'QIANFAN_API_KEYS',
-    envSingular:'QIANFAN_API_KEY',
-  },
-  {
-    name:       'modelstudio',
-    // Aliyun DashScope / Qwen (both qwen/* and modelstudio/* prefixes)
-    hostname:   /(?:^|\.)dashscope\.aliyuncs\.com$/i,
-    envPlural:  'MODELSTUDIO_API_KEYS',
-    envSingular:'MODELSTUDIO_API_KEY',
-  },
 
+const PROVIDERS = [
+  { name:'anthropic',    hostname:/(?:^|\.)api\.anthropic\.com$/i,            envPlural:'ANTHROPIC_API_KEYS',        envSingular:'ANTHROPIC_API_KEY' },
+  { name:'openai',       hostname:/(?:^|\.)api\.openai\.com$/i,               envPlural:'OPENAI_API_KEYS',           envSingular:'OPENAI_API_KEY' },
+  { name:'gemini',       hostname:/(?:^|\.)(?:generativelanguage\.googleapis\.com|aiplatform\.googleapis\.com)$/i,
+                                                                               envPlural:'GEMINI_API_KEYS',           envSingular:'GEMINI_API_KEY',  queryParam:true },
+  { name:'deepseek',     hostname:/(?:^|\.)api\.deepseek\.com$/i,             envPlural:'DEEPSEEK_API_KEYS',         envSingular:'DEEPSEEK_API_KEY' },
+  { name:'openrouter',   hostname:/(?:^|\.)openrouter\.ai$/i,                 envPlural:'OPENROUTER_API_KEYS',       envSingular:'OPENROUTER_API_KEY' },
+  { name:'kilocode',     hostname:/(?:^|\.)kilocode\.ai$/i,                   envPlural:'KILOCODE_API_KEYS',         envSingular:'KILOCODE_API_KEY' },
+  { name:'opencode',     hostname:/(?:^|\.)opencode\.ai$/i,                   envPlural:'OPENCODE_API_KEYS',         envSingular:'OPENCODE_API_KEY' },
+  { name:'zai',          hostname:/(?:^|\.)(?:z\.ai|open\.bigmodel\.cn)$/i,   envPlural:'ZAI_API_KEYS',             envSingular:'ZAI_API_KEY' },
+  // FIX: kimi-coding aur moonshot ek hi hostname share karte hain (api.moonshot.cn).
+  // Purani file mein dono alag entries thi — find() hamesha kimi-coding pick karta tha,
+  // MOONSHOT_API_KEYS kabhi use nahi hoti. Ab merged entry: dono pools combine honge.
+  { name:'kimi-moonshot',hostname:/(?:^|\.)api\.moonshot\.cn$/i,              envPlural:'KIMI_API_KEYS',            envSingular:'KIMI_API_KEY',
+    _extraPlural:'MOONSHOT_API_KEYS', _extraSingular:'MOONSHOT_API_KEY' },
+  { name:'minimax',      hostname:/(?:^|\.)api\.minimax\.chat$/i,             envPlural:'MINIMAX_API_KEYS',          envSingular:'MINIMAX_API_KEY' },
+  { name:'xiaomi',       hostname:/(?:^|\.)api\.xiaomi\.com$/i,               envPlural:'XIAOMI_API_KEYS',           envSingular:'XIAOMI_API_KEY' },
+  { name:'volcengine',   hostname:/(?:^|\.)(?:ark\.cn-beijing\.volces\.com|volcengineapi\.com)$/i,
+                                                                               envPlural:'VOLCANO_ENGINE_API_KEYS',  envSingular:'VOLCANO_ENGINE_API_KEY' },
+  { name:'byteplus',     hostname:/(?:^|\.)maas-api\.ml-platform-cn-beijing\.byteplus\.com$/i,
+                                                                               envPlural:'BYTEPLUS_API_KEYS',         envSingular:'BYTEPLUS_API_KEY' },
+  { name:'mistral',      hostname:/(?:^|\.)api\.mistral\.ai$/i,               envPlural:'MISTRAL_API_KEYS',          envSingular:'MISTRAL_API_KEY' },
+  { name:'xai',          hostname:/(?:^|\.)api\.x\.ai$/i,                     envPlural:'XAI_API_KEYS',              envSingular:'XAI_API_KEY' },
+  { name:'nvidia',       hostname:/(?:^|\.)(?:integrate\.api\.nvidia\.com|api\.nvidia\.com)$/i,
+                                                                               envPlural:'NVIDIA_API_KEYS',           envSingular:'NVIDIA_API_KEY' },
+  { name:'groq',         hostname:/(?:^|\.)api\.groq\.com$/i,                 envPlural:'GROQ_API_KEYS',             envSingular:'GROQ_API_KEY' },
+  { name:'cohere',       hostname:/(?:^|\.)api\.cohere\.(?:ai|com)$/i,        envPlural:'COHERE_API_KEYS',           envSingular:'COHERE_API_KEY' },
+  { name:'together',     hostname:/(?:^|\.)api\.together\.(?:xyz|ai)$/i,      envPlural:'TOGETHER_API_KEYS',         envSingular:'TOGETHER_API_KEY' },
+  { name:'cerebras',     hostname:/(?:^|\.)api\.cerebras\.ai$/i,              envPlural:'CEREBRAS_API_KEYS',         envSingular:'CEREBRAS_API_KEY' },
+  { name:'huggingface',  hostname:/(?:^|\.)(?:api-inference\.huggingface\.co|router\.huggingface\.co|huggingface\.co)$/i,
+                                                                               envPlural:'HUGGINGFACE_HUB_TOKENS',   envSingular:'HUGGINGFACE_HUB_TOKEN' },
+  { name:'venice',       hostname:/(?:^|\.)api\.venice\.ai$/i,                envPlural:'VENICE_API_KEYS',           envSingular:'VENICE_API_KEY' },
+  { name:'github-copilot',hostname:/(?:^|\.)api\.githubcopilot\.com$/i,       envPlural:'COPILOT_GITHUB_TOKENS',    envSingular:'COPILOT_GITHUB_TOKEN' },
+  { name:'qianfan',      hostname:/(?:^|\.)(?:aip|qianfan)\.baidubce\.com$/i, envPlural:'QIANFAN_API_KEYS',         envSingular:'QIANFAN_API_KEY' },
+  { name:'modelstudio',  hostname:/(?:^|\.)dashscope\.aliyuncs\.com$/i,       envPlural:'MODELSTUDIO_API_KEYS',      envSingular:'MODELSTUDIO_API_KEY' },
+  { name:'synthetic',    hostname:/(?:^|\.)synthetic\.local$/i,               envPlural:'SYNTHETIC_API_KEYS',        envSingular:'SYNTHETIC_API_KEY' },
 ];
 
 // ─── Key loading ─────────────────────────────────────────────────────────────
 
 function normalizeKeys(...inputs) {
-  const seen = new Set();
-  const out   = [];
-  for (const input of inputs) {
-    for (const k of String(input || '').split(',').map(s => s.trim()).filter(Boolean)) {
+  const seen = new Set(), out = [];
+  for (const input of inputs)
+    for (const k of String(input || '').split(',').map(s => s.trim()).filter(Boolean))
       if (!seen.has(k)) { seen.add(k); out.push(k); }
-    }
-  }
   return out;
 }
 
-// Build per-provider key pools + rotation indices
+// Per-key state: { strikes, blacklistedUntil }
+// strikes   – consecutive 429/402 count; resets on success
+// blacklistedUntil – epoch ms; 0 = active
+function makeKeyState() { return { strikes: 0, blacklistedUntil: 0 }; }
+
 const providerState = PROVIDERS.map(p => {
-  const llmFallbackRaw = String(process.env.LLM_API_KEY_FALLBACK_ENABLED || '').trim().toLowerCase();
-  const llmFallbackEnabled = !/^(0|false|no|off)$/.test(llmFallbackRaw);
+  const llmFallbackEnabled = !/^(0|false|no|off)$/.test(
+    String(process.env.LLM_API_KEY_FALLBACK_ENABLED || '').trim().toLowerCase(),
+  );
+
+  const extraKeys = (p._extraPlural || p._extraSingular)
+    ? normalizeKeys(process.env[p._extraPlural || ''] || '', process.env[p._extraSingular || ''] || '')
+    : [];
+
   const dedicatedKeys = normalizeKeys(
     process.env[p.envPlural]  || '',
     process.env[p.envSingular] || '',
+    ...extraKeys,
   );
   const hasDedicated = dedicatedKeys.length > 0;
   const keys = hasDedicated
     ? dedicatedKeys
-    : (
-      llmFallbackEnabled
-        ? normalizeKeys(process.env.LLM_API_KEY || '')
-        : []
-    );
+    : (llmFallbackEnabled ? normalizeKeys(process.env.LLM_API_KEY || '') : []);
 
-  if (hasDedicated) {
+  if (hasDedicated)
     log(`[key-rotator] ${p.name}: ${keys.length} key${keys.length === 1 ? '' : 's'}`);
-  } else if (!keys.length) {
-    console.warn(`[key-rotator] No keys for provider "${p.name}"`);
-  }
+  else if (!keys.length)
+    warn(`[key-rotator] No keys for provider "${p.name}"`);
 
-  return { ...p, keys, idx: 0 };
+  // keyState: Map<keyString, {strikes, blacklistedUntil}>
+  const keyState = new Map(keys.map(k => [k, makeKeyState()]));
+
+  // FIX: idx tracks position in the ACTIVE (non-permanently-removed) pool.
+  // We never remove keys from the array — we just skip blacklisted ones.
+  // idx advances only when a key is ACTUALLY picked (no drift for skipped keys).
+  return { ...p, keys, keyState, idx: 0 };
 });
 
-// Summarise providers that fall back to LLM_API_KEY
+// LLM_API_KEY fallback summary
 const fallbackCount = providerState.filter(p => {
-  const dedicated = normalizeKeys(
-    process.env[p.envPlural]  || '',
-    process.env[p.envSingular] || '',
-  );
-  return dedicated.length === 0 && p.keys.length > 0;
+  const ded = normalizeKeys(process.env[p.envPlural] || '', process.env[p.envSingular] || '');
+  return ded.length === 0 && p.keys.length > 0;
 }).length;
-if (fallbackCount > 0) {
+if (fallbackCount > 0)
   log(`[key-rotator] ${fallbackCount} provider(s) using LLM_API_KEY fallback`);
-} else if (process.env.LLM_API_KEY && /^(0|false|no|off)$/i.test(String(process.env.LLM_API_KEY_FALLBACK_ENABLED || ''))) {
-  log('[key-rotator] LLM_API_KEY fallback disabled (set LLM_API_KEY_FALLBACK_ENABLED=true to re-enable)');
+
+// ─── Per-key state helpers ────────────────────────────────────────────────────
+
+/**
+ * Is this key currently sitting out?
+ * Also auto-clears expired blacklists so the key re-enters the pool silently.
+ */
+function isActive(p, key) {
+  const ks = p.keyState.get(key);
+  if (!ks) return true;                          // unknown key → treat as active
+  if (ks.blacklistedUntil === 0) return true;    // not blacklisted
+  if (Date.now() >= ks.blacklistedUntil) {
+    ks.blacklistedUntil = 0;                     // expired → back in pool
+    log(`[key-rotator] ${p.name}: ...${key.slice(-6)} back in pool`);
+    return true;
+  }
+  return false;
 }
 
-// ─── Runtime helpers ─────────────────────────────────────────────────────────
+/**
+ * Called when a key gets a 429/402 response.
+ *
+ * Strike logic:
+ *   strike 1 → BASE_COOLDOWN_MS  (e.g. 60 s  — probably rate-limit)
+ *   strike 2 → BASE_COOLDOWN_MS × 4            (240 s)
+ *   strike 3 → PERM_BLACKLIST_MS (24 h — treat as quota exhausted, skip all day)
+ *
+ * A successful response resets strikes so a key that was temporarily
+ * rate-limited and recovered is treated as fresh again.
+ */
+function recordFailure(p, key) {
+  let ks = p.keyState.get(key);
+  if (!ks) { ks = makeKeyState(); p.keyState.set(key, ks); }
+
+  ks.strikes = Math.min(ks.strikes + 1, MAX_STRIKES);
+
+  let cooldown;
+  if (ks.strikes >= MAX_STRIKES) {
+    cooldown = PERM_BLACKLIST_MS;
+    warn(`[key-rotator] ${p.name}: ...${key.slice(-6)} reached ${MAX_STRIKES} strikes — suspended for 24 h (quota likely exhausted)`);
+  } else {
+    // Exponential: 1× → 4× (strikes 1 and 2)
+    cooldown = BASE_COOLDOWN_MS * Math.pow(4, ks.strikes - 1);
+    const secs = Math.round(cooldown / 1000);
+    log(`[key-rotator] ${p.name}: ...${key.slice(-6)} strike ${ks.strikes}/${MAX_STRIKES} — backoff ${secs}s`);
+  }
+
+  ks.blacklistedUntil = Date.now() + cooldown;
+}
+
+/**
+ * Called on any 2xx/3xx response — resets the key's strike counter.
+ */
+function recordSuccess(p, key) {
+  const ks = p.keyState.get(key);
+  if (ks && ks.strikes > 0) {
+    ks.strikes = 0;
+    log(`[key-rotator] ${p.name}: ...${key.slice(-6)} recovered — strikes reset`);
+  }
+}
+
+// ─── Round-robin selection ────────────────────────────────────────────────────
+
+/**
+ * Pick the next active key using round-robin.
+ *
+ * FIX (idx drift): idx advances by 1 per CALL, not per skip.
+ * We scan up to `total` positions from the current idx to find an active key.
+ * The found key's position becomes the new baseline for the next call.
+ *
+ * Example with 10 keys where k3–k7 are blacklisted:
+ *   call 1: start=0 → picks k0, next start=1
+ *   call 2: start=1 → picks k1, next start=2
+ *   call 3: start=2 → scans k2→active, picks k2, next start=3
+ *   call 4: start=3 → scans k3(skip)…k7(skip)→k8 active, picks k8, next start=9
+ *   call 5: start=9 → picks k9, next start=0
+ * Every active key gets equal share; blacklisted keys are cleanly skipped.
+ */
+function nextKey(p) {
+  if (!p || !p.keys.length) return null;
+
+  const total = p.keys.length;
+
+  for (let offset = 0; offset < total; offset++) {
+    const i   = (p.idx + offset) % total;
+    const key = p.keys[i];
+    if (isActive(p, key)) {
+      p.idx = (i + 1) % total;   // next call starts AFTER the key we just picked
+      return key;
+    }
+  }
+
+  // All keys are sitting out — pick the one closest to recovering
+  warn(`[key-rotator] ${p.name}: all ${total} key(s) suspended — using soonest-recovering key`);
+  let best = p.keys[0], bestExpiry = Infinity;
+  for (const k of p.keys) {
+    const exp = p.keyState.get(k)?.blacklistedUntil ?? 0;
+    if (exp < bestExpiry) { best = k; bestExpiry = exp; }
+  }
+  return best;
+}
+
+// ─── Auth header injection ────────────────────────────────────────────────────
 
 function resolveHostname(urlLike) {
   try {
     const u =
-      typeof urlLike === 'string'                              ? new URL(urlLike)
-      : urlLike instanceof URL                                 ? urlLike
-      : urlLike && typeof urlLike.url === 'string'             ? new URL(urlLike.url)
-      : urlLike && typeof urlLike.href === 'string'            ? new URL(urlLike.href)
-      : urlLike && typeof urlLike.hostname === 'string'        ? urlLike
+      typeof urlLike === 'string'                         ? new URL(urlLike)
+      : urlLike instanceof URL                            ? urlLike
+      : urlLike && typeof urlLike.url === 'string'        ? new URL(urlLike.url)
+      : urlLike && typeof urlLike.href === 'string'       ? new URL(urlLike.href)
+      : urlLike && typeof urlLike.hostname === 'string'   ? urlLike
       : null;
     return u ? u.hostname : null;
-  } catch {
-    return null;
-  }
+  } catch { return null; }
 }
 
 function matchProvider(hostname) {
@@ -270,126 +252,135 @@ function matchProvider(hostname) {
   return providerState.find(p => p.hostname.test(hostname)) || null;
 }
 
-function nextKey(provider) {
-  if (!provider || !provider.keys.length) return null;
-  const key = provider.keys[provider.idx % provider.keys.length];
-  provider.idx = (provider.idx + 1) % provider.keys.length;
-  return key;
-}
-
 function setAuthHeader(headers, key) {
   if (!key) return headers;
-  const authValue = `Bearer ${key}`;
-
+  const val = `Bearer ${key}`;
   if (typeof Headers !== 'undefined' && headers instanceof Headers) {
-    headers.set('authorization', authValue);
-    return headers;
+    headers.set('authorization', val); return headers;
   }
   if (Array.isArray(headers)) {
-    const out = headers.filter(([k]) => String(k).toLowerCase() !== 'authorization');
-    out.push(['authorization', authValue]);
-    return out;
+    return [...headers.filter(([k]) => String(k).toLowerCase() !== 'authorization'), ['authorization', val]];
   }
-  if (headers && typeof headers === 'object') {
-    return { ...headers, authorization: authValue };
+  if (headers && typeof headers === 'object') return { ...headers, authorization: val };
+  return { authorization: val };
+}
+
+function handleStatus(p, key, status) {
+  if (!p || !key) return;
+  if (status === 429 || status === 402) {
+    recordFailure(p, key);
+  } else if (status >= 200 && status < 400) {
+    recordSuccess(p, key);
   }
-  return { authorization: authValue };
 }
 
 // ─── Patch globalThis.fetch ───────────────────────────────────────────────────
 
 function patchFetch() {
   if (typeof globalThis.fetch !== 'function') return;
-
-  const originalFetch = globalThis.fetch.bind(globalThis);
+  const orig = globalThis.fetch.bind(globalThis);
 
   globalThis.fetch = async function patchedFetch(input, init = {}) {
-    try {
-      const urlLike =
-        typeof input === 'string' || input instanceof URL
-          ? input
-          : input && typeof input.url === 'string' ? input.url : null;
+    let usedKey = null, usedProvider = null;
 
-      const hostname = resolveHostname(urlLike);
-      const provider = matchProvider(hostname);
+    try {
+      const urlLike = typeof input === 'string' || input instanceof URL
+        ? input
+        : (input && typeof input.url === 'string' ? input.url : null);
+      const provider = matchProvider(resolveHostname(urlLike));
 
-            if (provider) {
+      if (provider) {
         const key = nextKey(provider);
         if (key) {
+          usedKey = key; usedProvider = provider;
           if (provider.queryParam) {
-            // Gemini: key URL query param mein jaata hai, Bearer nahi
             const url = new URL(typeof input === 'string' ? input : input.url);
             url.searchParams.set('key', key);
-            input = typeof input === 'string' ? url.toString() : new Request(url.toString(), input);
+            if (typeof input === 'string') {
+              input = url.toString();
+            } else {
+              init = { method:input.method, headers:input.headers, body:input.body,
+                       mode:input.mode, credentials:input.credentials, cache:input.cache,
+                       redirect:input.redirect, referrer:input.referrer,
+                       integrity:input.integrity, ...init };
+              input = url.toString();
+            }
           } else {
-            const headers        = init.headers || (input && input.headers) || undefined;
-            const patchedHeaders = setAuthHeader(headers, key);
-            init = { ...init, headers: patchedHeaders };
-            // NOTE: new Request(input, {headers}) yahan nahi karte — Request clone karna
-            // body stream ko disturb kar deta hai → UND_ERR_INVALID_ARG on POST requests.
-            // init.headers fetch spec ke mutabiq Request ke headers ko override kar deta hai.
+            init = { ...init, headers: setAuthHeader(init.headers || (input && input.headers) || undefined, key) };
           }
         }
       }
-    } catch (err) {
-      console.warn('[key-rotator] fetch patch error:', err?.message || err);
-    }
+    } catch (err) { warn('[key-rotator] fetch patch error:', err?.message || err); }
 
-    return originalFetch(input, init);
+    let response;
+    try { response = await orig(input, init); }
+    catch (err) { throw err; }
+
+    try { handleStatus(usedProvider, usedKey, response.status); } catch (_) {}
+    return response;
   };
 }
 
 // ─── Patch node:http / node:https ────────────────────────────────────────────
 
 function patchHttpModule(mod) {
-  const originalRequest = mod.request;
+  const orig = mod.request;
 
   mod.request = function patchedRequest(...args) {
+    let usedKey = null, usedProvider = null;
+
     try {
       const options  = args[0];
-      const hostname = resolveHostname(options);
-      const provider = matchProvider(hostname);
+      const provider = matchProvider(resolveHostname(options));
 
       if (provider) {
         const key = nextKey(provider);
         if (key) {
+          usedKey = key; usedProvider = provider;
           if (provider.queryParam) {
-            // Gemini: ?key= query param use karo
-            const u = new URL(String(typeof options === 'string' || options instanceof URL ? options : `https://${options.hostname}${options.path || '/'}`));
+            const u = new URL(String(
+              typeof options === 'string' || options instanceof URL
+                ? options
+                : `https://${options.hostname}${options.path || '/'}`
+            ));
             u.searchParams.set('key', key);
             args[0] = typeof options === 'object' && !(options instanceof URL)
-              ? { ...options, path: `${u.pathname}${u.search}` }
+              ? { ...options, path:`${u.pathname}${u.search}` }
               : u.toString();
           } else if (typeof options === 'string' || options instanceof URL) {
-            // Convert string/URL to options object and inject auth header.
-            // Also preserve any extra options passed as args[1] (3-arg form of http.request).
             const u = new URL(String(options));
-            const extraOpts = (args[1] && typeof args[1] === 'object' && typeof args[1].on !== 'function') ? args[1] : {};
-            args[0] = {
-              protocol: u.protocol,
-              hostname: u.hostname,
-              port:     u.port,
-              path:     `${u.pathname}${u.search}`,
-              ...extraOpts,
-              headers:  setAuthHeader(extraOpts.headers, key),
-            };
+            const extra = (args[1] && typeof args[1] === 'object' && typeof args[1].on !== 'function') ? args[1] : {};
+            args[0] = { protocol:u.protocol, hostname:u.hostname, port:u.port,
+                        path:`${u.pathname}${u.search}`, ...extra,
+                        headers:setAuthHeader(extra.headers, key) };
           } else if (options && typeof options === 'object') {
-            args[0] = { ...options, headers: setAuthHeader(options.headers, key) };
+            args[0] = { ...options, headers:setAuthHeader(options.headers, key) };
           }
         }
       }
-    } catch (err) {
-      console.warn('[key-rotator] http patch error:', err?.message || err);
-    }
+    } catch (err) { warn('[key-rotator] http patch error:', err?.message || err); }
+
+    const req = orig.apply(mod, args);
 
-    return originalRequest.apply(mod, args);
+    // Intercept response to track 429/success
+    if (usedProvider && usedKey) {
+      const _emit = req.emit.bind(req);
+      req.emit = function (event, ...rest) {
+        if (event === 'response') {
+          const res = rest[0];
+          try { handleStatus(usedProvider, usedKey, res?.statusCode); } catch (_) {}
+        }
+        return _emit(event, ...rest);
+      };
+    }
+    return req;
   };
 }
 
-// ─── Apply patches ────────────────────────────────────────────────────────────
+// ─── Boot ─────────────────────────────────────────────────────────────────────
 
 patchFetch();
 patchHttpModule(http);
 patchHttpModule(https);
 
-log('[key-rotator] loaded — all providers active');
+log(`[key-rotator] loaded — cooldown base:${BASE_COOLDOWN_MS/1000}s max-strikes:${MAX_STRIKES} perm-suspend:24h`);

openclaw-sync.py

@@ -50,6 +50,7 @@ CONFIG_SETTLE_SECONDS = max(
     0.0,
     float(os.environ.get("OPENCLAW_CONFIG_SETTLE_SECONDS", "3")),
 )
+SESSIONS_MIN_SYNC_GAP = int(os.environ.get("SESSIONS_MIN_SYNC_GAP", "30"))
 HF_TOKEN = os.environ.get("HF_TOKEN", "").strip()
 HF_USERNAME = os.environ.get("HF_USERNAME", "").strip()
 SPACE_AUTHOR_NAME = os.environ.get("SPACE_AUTHOR_NAME", "").strip()
@@ -75,12 +76,14 @@ EXCLUDED_STATE_NAMES = {
     "browser",
     "npm",
 }
+SESSIONS_ROOT = OPENCLAW_HOME / "agents"
 WHATSAPP_CREDS_DIR = OPENCLAW_HOME / "credentials" / "whatsapp" / "default"
 WHATSAPP_BACKUP_DIR = STATE_DIR / "credentials" / "whatsapp" / "default"
 RESET_MARKER = WORKSPACE / ".reset_credentials"
 HF_API = HfApi(token=HF_TOKEN) if HF_TOKEN else None
 STOP_EVENT = threading.Event()
 _REPO_ID_CACHE: str | None = None
+_SESSIONS_FILE_DIGEST_CACHE: dict[str, tuple[int, int, int, str]] = {}
 WorkspaceMarker: TypeAlias = tuple[int, int, int, str]
 
 
@@ -108,6 +111,35 @@ def count_files(path: Path) -> int:
     return sum(1 for child in path.rglob("*") if child.is_file())
 
 
+def copy_state_entry_with_retry(source_path: Path, backup_path: Path, attempts: int = 3) -> None:
+    """Copy one top-level .openclaw entry with short retries for hot files/dirs."""
+    last_exc: Exception | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            if backup_path.exists():
+                if backup_path.is_dir():
+                    shutil.rmtree(backup_path, ignore_errors=True)
+                else:
+                    backup_path.unlink(missing_ok=True)
+            if source_path.is_dir():
+                shutil.copytree(source_path, backup_path)
+                return
+            if source_path.is_file():
+                shutil.copy2(source_path, backup_path)
+                return
+            return
+        except Exception as exc:
+            last_exc = exc
+            if attempt < attempts:
+                time.sleep(0.2 * attempt)
+                if backup_path.exists():
+                    if backup_path.is_dir():
+                        shutil.rmtree(backup_path, ignore_errors=True)
+                    else:
+                        backup_path.unlink(missing_ok=True)
+                continue
+            raise last_exc
+
 def snapshot_state_into_workspace() -> None:
     try:
         STATE_DIR.mkdir(parents=True, exist_ok=True)
@@ -117,18 +149,47 @@ def snapshot_state_into_workspace() -> None:
         staging_dir = STATE_DIR / ".openclaw-staging"
         if staging_dir.exists():
             shutil.rmtree(staging_dir, ignore_errors=True)
-        staging_dir.mkdir(parents=True, exist_ok=True)
+        if OPENCLAW_STATE_BACKUP_DIR.exists():
+            shutil.copytree(OPENCLAW_STATE_BACKUP_DIR, staging_dir)
+        else:
+            staging_dir.mkdir(parents=True, exist_ok=True)
 
+        skipped_entries: list[tuple[str, Exception]] = []
+        copied_entry_names: set[str] = set()
         for source_path in OPENCLAW_HOME.iterdir():
             if source_path.name in EXCLUDED_STATE_NAMES:
                 continue
 
             backup_path = staging_dir / source_path.name
-            if source_path.is_dir():
-                shutil.copytree(source_path, backup_path)
-            elif source_path.is_file():
-                shutil.copy2(source_path, backup_path)
-
+            try:
+                copy_state_entry_with_retry(source_path, backup_path)
+                copied_entry_names.add(source_path.name)
+            except Exception as entry_exc:
+                skipped_entries.append((source_path.name, entry_exc))
+
+        # If staging was seeded from a previous backup, remove entries that no
+        # longer exist in OPENCLAW_HOME so the backup remains a true mirror of
+        # current state (except entries intentionally excluded from sync).
+        for staged_path in list(staging_dir.iterdir()):
+            if staged_path.name in EXCLUDED_STATE_NAMES:
+                continue
+            if staged_path.name in copied_entry_names:
+                continue
+            if staged_path.exists():
+                if staged_path.is_dir():
+                    shutil.rmtree(staged_path, ignore_errors=True)
+                else:
+                    staged_path.unlink(missing_ok=True)
+
+        # If any top-level state entries could not be copied, keep the last
+        # known-good version for only those entries (staging was seeded from
+        # previous backup). This preserves forward progress for the rest.
+        if skipped_entries:
+            for name, entry_exc in skipped_entries:
+                print(f"Warning: keeping previous state entry {name}: {entry_exc}")
+            print(
+                "Warning: OpenClaw state snapshot had copy failures; updated remaining state entries."
+            )
         # Atomically swap staging → real backup dir
         if OPENCLAW_STATE_BACKUP_DIR.exists():
             shutil.rmtree(OPENCLAW_STATE_BACKUP_DIR, ignore_errors=True)
@@ -525,6 +586,86 @@ def is_valid_json_file(path: Path) -> bool:
         return False
 
 
+def sessions_marker() -> tuple[int, int, int, str]:
+    """Return a lightweight marker for all agent session directories.
+
+    OpenClaw can use agent profiles beyond "main". Watch every
+    */sessions path under .openclaw/agents so session changes always trigger
+    syncs regardless of profile name.
+    """
+    if not SESSIONS_ROOT.exists():
+        return (0, 0, 0, "")
+
+    file_count = 0
+    total_size = 0
+    newest_mtime = 0
+    metadata_hasher = hashlib.sha256()
+
+    global _SESSIONS_FILE_DIGEST_CACHE
+    next_cache: dict[str, tuple[int, int, int, str]] = {}
+
+    for profile_dir in sorted(SESSIONS_ROOT.iterdir()):
+        if not profile_dir.is_dir():
+            continue
+        sessions_dir = profile_dir / "sessions"
+        if not sessions_dir.exists():
+            continue
+        # Use content fingerprinting for sessions so we detect changes even
+        # when file size + mtime metadata appear unchanged across quick writes.
+        # (Some tooling can rewrite files in-place with preserved timestamps.)
+        marker = metadata_marker(sessions_dir)
+        digest = hashlib.sha256()
+        for path in sorted(p for p in sessions_dir.rglob("*") if p.is_file()):
+            rel = path.relative_to(sessions_dir).as_posix()
+            try:
+                stat = path.stat()
+            except OSError:
+                continue
+            size = int(stat.st_size)
+            mtime_ns = int(stat.st_mtime_ns)
+            ctime_ns = int(stat.st_ctime_ns)
+            cache_key = f"{profile_dir.name}\0{rel}"
+            digest.update(rel.encode("utf-8"))
+            digest.update(b"\0")
+            digest.update(str(size).encode("ascii"))
+            digest.update(b"\0")
+            digest.update(str(mtime_ns).encode("ascii"))
+            digest.update(b"\0")
+            digest.update(str(ctime_ns).encode("ascii"))
+            digest.update(b"\0")
+            cached = _SESSIONS_FILE_DIGEST_CACHE.get(cache_key)
+            if (
+                cached is not None
+                and cached[0] == size
+                and cached[1] == mtime_ns
+                and cached[2] == ctime_ns
+            ):
+                file_digest = cached[3]
+            else:
+                file_hasher = hashlib.sha256()
+                try:
+                    with path.open("rb") as handle:
+                        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                            file_hasher.update(chunk)
+                except (FileNotFoundError, IsADirectoryError, NotADirectoryError):
+                    continue
+                file_digest = file_hasher.hexdigest()
+            next_cache[cache_key] = (size, mtime_ns, ctime_ns, file_digest)
+            digest.update(file_digest.encode("ascii"))
+            digest.update(b"\0")
+
+        file_count += marker[0]
+        total_size += marker[1]
+        newest_mtime = max(newest_mtime, marker[2])
+        metadata_hasher.update(profile_dir.name.encode("utf-8"))
+        metadata_hasher.update(b"\0")
+        metadata_hasher.update(digest.hexdigest().encode("ascii"))
+        metadata_hasher.update(b"\0")
+
+    _SESSIONS_FILE_DIGEST_CACHE = next_cache
+    return (file_count, total_size, newest_mtime, metadata_hasher.hexdigest())
+
+
 def wait_for_config_settle(config_marker: tuple[int, int, int]) -> tuple[str, tuple[int, int, int]]:
     stable_since = time.monotonic()
     current_marker = config_marker
@@ -547,14 +688,32 @@ def wait_for_config_settle(config_marker: tuple[int, int, int]) -> tuple[str, tu
     return ("stopped", current_marker)
 
 
-def wait_for_sync_trigger(config_marker: tuple[int, int, int]) -> tuple[str, tuple[int, int, int]]:
+def wait_for_sync_trigger(
+    config_marker: tuple[int, int, int],
+    last_sessions_sync_time: float = 0.0,
+) -> tuple[str, tuple[int, int, int]]:
     deadline = time.monotonic() + max(0, INTERVAL)
+    # BUG FIX: also watch sessions directory so new/updated sessions
+    # trigger an immediate sync instead of waiting the full interval.
+    # Without this, sessions created between 180-second intervals were
+    # lost when the container restarted (e.g. HF Space going to sleep).
+    last_sessions_marker = sessions_marker()
 
     while not STOP_EVENT.is_set():
         current_config_marker = file_marker(OPENCLAW_CONFIG_FILE)
         if current_config_marker != config_marker:
             return wait_for_config_settle(current_config_marker)
 
+        sessions_gap_elapsed = (
+            time.monotonic() - last_sessions_sync_time >= SESSIONS_MIN_SYNC_GAP
+        )
+        if sessions_gap_elapsed:
+            # Sessions changed -> trigger sync immediately (no settle needed;
+            # session files are written atomically by OpenClaw).
+            current_sessions_marker = sessions_marker()
+            if current_sessions_marker != last_sessions_marker:
+                return ("sessions", current_config_marker)
+
         remaining = deadline - time.monotonic()
         if remaining <= 0:
             return ("interval", current_config_marker)
@@ -610,11 +769,16 @@ def loop() -> int:
         print("Initial workspace fingerprint captured.")
 
     config_marker = file_marker(OPENCLAW_CONFIG_FILE)
+    last_sessions_sync_time = 0.0
+
+    sync_trigger = "startup"
 
     while not STOP_EVENT.is_set():
         try:
             sync_started_config_marker = file_marker(OPENCLAW_CONFIG_FILE)
             last_fingerprint, last_marker = sync_once(last_fingerprint, last_marker)
+            if sync_trigger == "sessions":
+                last_sessions_sync_time = time.monotonic()
             config_marker = file_marker(OPENCLAW_CONFIG_FILE)
 
             if config_marker != sync_started_config_marker:
@@ -627,12 +791,19 @@ def loop() -> int:
             write_status("error", f"Sync failed: {exc}")
             print(f"Workspace sync failed: {exc}")
             config_marker = file_marker(OPENCLAW_CONFIG_FILE)
+            STOP_EVENT.wait(min(30, SESSIONS_MIN_SYNC_GAP))
 
-        trigger, config_marker = wait_for_sync_trigger(config_marker)
+        trigger, config_marker = wait_for_sync_trigger(
+            config_marker,
+            last_sessions_sync_time=last_sessions_sync_time,
+        )
         if trigger == "stopped":
             break
         if trigger == "settled":
             print("OpenClaw config changed and settled; syncing immediately.")
+        if trigger == "sessions":
+            print("Session files changed; syncing immediately.")
+        sync_trigger = trigger
 
     return 0
 

start.sh

@@ -42,6 +42,9 @@ try:
             continue
         if str(key) in {"HUGGINGCLAW_ENV_BUNDLE", "ENV_BUNDLE"}:
             continue
+        if str(key) == "OPENCLAW_VERSION":
+            print("Warning: OPENCLAW_VERSION from env bundle is ignored (build-time only; set HF Variable and rebuild).", file=sys.stderr)
+            continue
         if os.environ.get(str(key), ""):
             continue
         if value is None or isinstance(value, (dict, list)):
@@ -96,6 +99,11 @@ if [ "$DEV_MODE_ENABLED" != "true" ] && [ -z "${DEV_MODE:-}" ] && [ -n "${GATEWA
   DEV_MODE_ENABLED=true
   : # auto-enable is silent; set DEV_MODE=false to opt out
 fi
+if [ "$DEV_MODE_ENABLED" = "true" ]; then
+  export DEV_MODE=true
+else
+  export DEV_MODE=false
+fi
 SYNC_INTERVAL="$(trim_var "${SYNC_INTERVAL:-180}")"
 DEVDATA_DATASET_NAME="$(trim_var "${DEVDATA_DATASET_NAME:-huggingclaw-devdata}")"
 DEVDATA_SYNC_INTERVAL="$(trim_var "${DEVDATA_SYNC_INTERVAL:-180}")"
@@ -105,6 +113,9 @@ DEVDATA_ENABLED=true
 if ! hc_is_true "$DEVDATA_NORMALIZED"; then
   DEVDATA_ENABLED=false
 fi
+# On HF Spaces, browser is disabled by default (no display server).
+# To enable: set BROWSER_PLUGIN_MODE=enabled as an HF Space secret.
+# WARNING: requires at least CPU Upgrade tier (2 vCPU / 16GB RAM).
 if [ -n "${SPACE_HOST:-}" ]; then
   OPENCLAW_CONSOLE_LOG_LEVEL="${OPENCLAW_CONSOLE_LOG_LEVEL:-warn}"
   OPENCLAW_FILE_LOG_LEVEL="${OPENCLAW_FILE_LOG_LEVEL:-info}"
@@ -197,7 +208,7 @@ case "$LLM_PROVIDER" in
   byteplus|byteplus-plan)       export BYTEPLUS_API_KEY="$LLM_API_KEY" ;;
   qianfan)                      export QIANFAN_API_KEY="$LLM_API_KEY" ;;
   # ── Western Providers ──
-  mistral|mistralai)            export MISTRAL_API_KEY="$LLM_API_KEY" ;;
+  mistral)                      export MISTRAL_API_KEY="$LLM_API_KEY" ;;
   xai|x-ai)                     export XAI_API_KEY="$LLM_API_KEY" ;;
   nvidia)                       export NVIDIA_API_KEY="$LLM_API_KEY" ;;
   cohere)                       export COHERE_API_KEY="$LLM_API_KEY" ;;
@@ -208,8 +219,18 @@ case "$LLM_PROVIDER" in
   venice)                       export VENICE_API_KEY="$LLM_API_KEY" ;;
   synthetic)                    export SYNTHETIC_API_KEY="$LLM_API_KEY" ;;
   github-copilot)               export COPILOT_GITHUB_TOKEN="$LLM_API_KEY" ;;
+  llama-3.*|llama-4.*|mixtral-*|gemma-*)
+    export GROQ_API_KEY="$LLM_API_KEY"
+    echo "Note: bare Groq model '$LLM_MODEL' detected; mapped LLM_API_KEY → GROQ_API_KEY. Use 'groq/${LLM_MODEL}' prefix to be explicit." ;;
+  mistral-*|codestral-*|devstral-*|voxtral-*)
+    export MISTRAL_API_KEY="$LLM_API_KEY"
+    echo "Note: bare Mistral model '$LLM_MODEL' detected; mapped LLM_API_KEY → MISTRAL_API_KEY. Use 'mistral/${LLM_MODEL}' prefix to be explicit." ;;
+  moonshotai|meta-llama|deepseek-ai|MiniMaxAI|minimax-ai|Qwen|zai-org|mistralai|google)
+    echo "Warning: LLM_MODEL='$LLM_MODEL' uses sub-provider prefix '$LLM_PROVIDER'. This is a router-namespaced model (Together/OpenRouter). Mapping LLM_API_KEY → TOGETHER_API_KEY. If using OpenRouter, also set OPENROUTER_API_KEY as a separate secret."
+    export TOGETHER_API_KEY="${TOGETHER_API_KEY:-$LLM_API_KEY}" ;;
   # ── Fallback: Anthropic (default) ──
   *)
+    echo "Warning: Unknown provider prefix '$LLM_PROVIDER' in LLM_MODEL='$LLM_MODEL'. Defaulting to ANTHROPIC_API_KEY. If using a router-namespaced model (e.g. moonshotai/Kimi-K2.5), set TOGETHER_API_KEY or OPENROUTER_API_KEY as a separate secret."
     export ANTHROPIC_API_KEY="$LLM_API_KEY"
     ;;
 esac
@@ -234,7 +255,6 @@ promote_first_pool_key() {
 promote_first_pool_key "ANTHROPIC_API_KEY" "ANTHROPIC_API_KEYS"
 promote_first_pool_key "OPENAI_API_KEY" "OPENAI_API_KEYS"
 promote_first_pool_key "GEMINI_API_KEY" "GEMINI_API_KEYS"
-promote_first_pool_key "GEMINI_API_KEY" "GOOGLE_API_KEYS"
 promote_first_pool_key "DEEPSEEK_API_KEY" "DEEPSEEK_API_KEYS"
 promote_first_pool_key "OPENROUTER_API_KEY" "OPENROUTER_API_KEYS"
 promote_first_pool_key "KILOCODE_API_KEY" "KILOCODE_API_KEYS"
@@ -268,11 +288,6 @@ if [ -z "${MOONSHOT_API_KEY:-}" ] && [ -n "${KIMI_API_KEY:-}" ]; then
 fi
 promote_first_pool_key "HUGGINGFACE_HUB_TOKEN" "HUGGINGFACE_HUB_TOKENS"
 
-# Compatibility aliases for Google provider secrets some users already have.
-if [ -z "${GEMINI_API_KEY:-}" ] && [ -n "${GOOGLE_API_KEY:-}" ]; then
-  export GEMINI_API_KEY="$GOOGLE_API_KEY"
-fi
-
 # ── Setup directories ──
 mkdir -p /home/node/.openclaw/agents/main/sessions
 mkdir -p /home/node/.openclaw/credentials
@@ -307,7 +322,7 @@ else
   echo "HF_TOKEN not set — running without dataset persistence."
 fi
 
-CLOUDFLARE_WORKERS_TOKEN="${CLOUDFLARE_WORKERS_TOKEN:-${CLOUDFLARE_API_TOKEN:-}}"
+CLOUDFLARE_WORKERS_TOKEN="${CLOUDFLARE_WORKERS_TOKEN:-}"
 export CLOUDFLARE_WORKERS_TOKEN
 CF_PROXY_ENV_FILE="/tmp/huggingclaw-cloudflare-proxy.env"
 if [ -n "${CLOUDFLARE_WORKERS_TOKEN:-}" ] || [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
@@ -326,7 +341,7 @@ CONFIG_JSON=$(cat <<'CONFIGEOF'
 {
   "gateway": {
     "mode": "local",
-    "port": 7860,
+    "port": "${GATEWAY_PORT}",
     "bind": "lan",
     "auth": {
       "token": ""
@@ -359,8 +374,10 @@ CONFIG_JSON=$(jq \
   --arg fileLevel "$OPENCLAW_FILE_LOG_LEVEL" \
   --arg consoleLevel "$OPENCLAW_CONSOLE_LOG_LEVEL" \
   --arg consoleStyle "$OPENCLAW_CONSOLE_LOG_STYLE" \
+  --arg port "$GATEWAY_PORT" \
   '.gateway.auth.token = $token
    | .agents.defaults.model = $model
+   | .gateway.port = ($port | tonumber)
    | .logging.level = $fileLevel
    | .logging.consoleLevel = $consoleLevel
    | .logging.consoleStyle = $consoleStyle' <<<"$CONFIG_JSON")
@@ -373,7 +390,7 @@ 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}"
+CUSTOM_MAX_TOKENS="${CUSTOM_MAX_TOKENS:-8192}"
 
 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:]')
@@ -464,8 +481,10 @@ inject_provider_models_from_env() {
   CONFIG_JSON=$(jq \
     --arg provider "$provider" \
     --argjson models "$models_json" \
-    '.models.mode = "merge"
-     | .models.providers[$provider] = ((.models.providers[$provider] // {}) + {models: $models})' <<<"$CONFIG_JSON")
+    'if .models.providers[$provider] then
+       .models.mode = "merge"
+       | .models.providers[$provider].models = $models
+     else . end' <<<"$CONFIG_JSON")
 }
 
 # Built-in provider model envs (optional)
@@ -510,12 +529,76 @@ inject_provider_models_from_env "github-copilot" "GITHUB_COPILOT_MODELS" "COPILO
 
 # 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
+BROWSER_WRAPPER_PATH=""
+HAS_FILE_CMD=false
+if command -v file >/dev/null 2>&1; then
+  HAS_FILE_CMD=true
+fi
+
+ensure_chromium_for_browser_plugin() {
+  # Enforce Chromium availability when browser plugin is explicitly enabled.
+  [ "$BROWSER_PLUGIN_MODE" = "enabled" ] || return 0
+  for candidate in /usr/lib/chromium/chromium /usr/bin/chromium /usr/bin/chromium-browser; do
+    [ -x "$candidate" ] && return 0
+  done
+  if [ "$HAS_FILE_CMD" != "true" ]; then
+    echo "BROWSER_PLUGIN_MODE=enabled and 'file' command is missing; attempting runtime install..."
+    if _hc_apt_install file; then
+      HAS_FILE_CMD=true
+      echo "'file' command installed via apt-get."
+    else
+      echo "Warning: could not install 'file'; continuing with executable-path fallback checks."
+    fi
+  fi
+  echo "BROWSER_PLUGIN_MODE=enabled but Chromium is missing; attempting runtime install..."
+  if _hc_apt_install chromium; then
+    echo "Chromium installed via apt-get."
+    return 0
+  fi
+  if _hc_apt_install chromium-browser; then
+    echo "Chromium browser package installed via apt-get."
+    return 0
+  fi
+  echo "ERROR: Browser plugin is enabled, but Chromium install failed. Disable browser plugin or rebuild image with Chromium preinstalled." >&2
+  return 1
+}
+HC_STARTUP_FAILURES=0
+ensure_chromium_for_browser_plugin || HC_STARTUP_FAILURES=$((HC_STARTUP_FAILURES + 1))
+
+# On Debian/Ubuntu, /usr/bin/chromium is often a shell wrapper while the real
+# ELF binary lives under /usr/lib/chromium/*. Prefer a real ELF binary, then
+# fall back to wrapper launchers (Playwright/OpenClaw can execute those too).
+for candidate in \
+    /usr/lib/chromium/chromium \
+    /usr/lib/chromium-browser/chromium-browser \
+    /usr/bin/chromium \
+    /usr/bin/chromium-browser \
+    /snap/bin/chromium; do
   if [ -x "$candidate" ]; then
-    BROWSER_EXECUTABLE_PATH="$candidate"
-    break
+    if [ "$HAS_FILE_CMD" = "true" ]; then
+      if file "$candidate" 2>/dev/null | grep -q "ELF"; then
+        BROWSER_EXECUTABLE_PATH="$candidate"
+        break
+      fi
+    else
+      # Minimal images may not ship `file`; accept the first executable path.
+      BROWSER_EXECUTABLE_PATH="$candidate"
+      break
+    fi
+    if [ -z "$BROWSER_WRAPPER_PATH" ]; then
+      BROWSER_WRAPPER_PATH="$candidate"
+    fi
   fi
 done
+if [ -z "$BROWSER_EXECUTABLE_PATH" ] && [ -n "$BROWSER_WRAPPER_PATH" ]; then
+  BROWSER_EXECUTABLE_PATH="$BROWSER_WRAPPER_PATH"
+  echo "No ELF Chromium binary found; using launcher wrapper at $BROWSER_EXECUTABLE_PATH"
+elif [ -n "$BROWSER_EXECUTABLE_PATH" ] && [ "$HAS_FILE_CMD" != "true" ]; then
+  echo "Detected Chromium executable at $BROWSER_EXECUTABLE_PATH (ELF probe skipped: 'file' command not installed)"
+fi
+if [ -z "$BROWSER_EXECUTABLE_PATH" ]; then
+  echo "Warning: Chromium executable not found. Browser plugin will be disabled."
+fi
 
 BROWSER_SHOULD_ENABLE=false
 if [ "$BROWSER_PLUGIN_MODE" = "enabled" ] && [ -n "$BROWSER_EXECUTABLE_PATH" ] && [ -x "$BROWSER_EXECUTABLE_PATH" ]; then
@@ -567,13 +650,28 @@ CONFIG_JSON=$(jq \
 
 if [ "$BROWSER_SHOULD_ENABLE" = "true" ]; then
   CONFIG_JSON=$(jq \
-    --arg execPath "$BROWSER_EXECUTABLE_PATH" \
     '.browser = {
        "enabled": true,
        "defaultProfile": "openclaw",
        "headless": true,
        "noSandbox": true,
-       "executablePath": $execPath
+       "extraArgs": [
+         "--headless=new",
+         "--no-sandbox",
+         "--disable-setuid-sandbox",
+         "--no-zygote",
+         "--disable-dev-shm-usage",
+         "--disable-gpu",
+         "--remote-debugging-address=127.0.0.1",
+         "--disable-features=UseDBus,MediaRouter",
+         "--password-store=basic",
+         "--no-first-run",
+         "--disable-background-networking",
+         "--disable-sync",
+         "--disable-translate",
+         "--disable-notifications",
+         "--disable-speech-api"
+       ]
      }
      | .agents.defaults.sandbox.browser.allowHostControl = true' <<<"$CONFIG_JSON")
 fi
@@ -588,7 +686,7 @@ CONFIG_JSON=$(jq \
    | (if $spaceHost != "" then
         .gateway.controlUi.allowedOrigins = ["https://" + $spaceHost]
       else . end)
-   | (if $password != "" then
+   | (if ($password != "" and (.gateway.auth.token // "") == "") then
         .gateway.auth.mode = "password" | .gateway.auth.password = $password
       else . end)' <<<"$CONFIG_JSON")
 
@@ -684,6 +782,10 @@ WHATSAPP_CONFIG_ENABLED=false
 if [ "$WHATSAPP_ENABLED_NORMALIZED" = "true" ]; then
   WHATSAPP_CONFIG_ENABLED=true
 fi
+TELEGRAM_CONFIG_ENABLED=false
+if [ -n "${TELEGRAM_BOT_TOKEN:-}" ]; then
+  TELEGRAM_CONFIG_ENABLED=true
+fi
 if [ -f "$EXISTING_CONFIG" ]; then
   echo "Restored config found — patching required fields and runtime channel/plugin toggles..."
   PATCHED=$(jq \
@@ -698,9 +800,11 @@ if [ -f "$EXISTING_CONFIG" ]; then
     --argjson consoleStyleConfigured "$OPENCLAW_CONSOLE_LOG_STYLE_CONFIGURED" \
     --argjson whatsappConfigured "$WHATSAPP_ENABLED_CONFIGURED" \
     --argjson whatsappEnabled "$WHATSAPP_CONFIG_ENABLED" \
+    --argjson telegramConfigured "$TELEGRAM_CONFIG_ENABLED" \
     '(.channels.whatsapp // {}) as $existingWhatsapp
      | .gateway.auth.token = $token
      | .agents.defaults.model = $model
+     | .gateway.port = ($desired.gateway.port // .gateway.port)
      | if $fileLogConfigured then .logging.level = $fileLevel else . end
      | if $consoleLogConfigured then .logging.consoleLevel = $consoleLevel else . end
      | if $consoleStyleConfigured then .logging.consoleStyle = $consoleStyle else . end
@@ -719,6 +823,13 @@ if [ -f "$EXISTING_CONFIG" ]; then
          | del(.channels.whatsapp)
        else
          .
+       end
+     | if $telegramConfigured then
+         .channels.telegram = (($desired.channels.telegram // {}) * (.channels.telegram // {}))
+         | .channels.telegram.botToken = $desired.channels.telegram.botToken
+       else
+         del(.channels.telegram)
+         | .plugins.entries.telegram.enabled = false
        end' \
     "$EXISTING_CONFIG" 2>/dev/null)
 
@@ -762,7 +873,13 @@ fi
 if [ -n "${CLOUDFLARE_PROXY_URL:-}" ]; then
   echo "Proxy     : ${CLOUDFLARE_PROXY_URL}"
 fi
-RUNTIME_JUPYTER_ENABLED="$DEV_MODE_ENABLED"
+# HUGGINGCLAW_JUPYTER_ENABLED env var se override allow karo
+# (env-builder "Enable Jupyter terminal" toggle yahi set karta hai)
+if hc_is_true "${HUGGINGCLAW_JUPYTER_ENABLED:-false}"; then
+  RUNTIME_JUPYTER_ENABLED=true
+else
+  RUNTIME_JUPYTER_ENABLED="$DEV_MODE_ENABLED"
+fi
 # Add user bin to PATH for jupyter-lab (installed in Dockerfile when DEV_MODE=true)
 export PATH="$HOME/.local/bin:$PATH"
 
@@ -807,6 +924,17 @@ graceful_shutdown() {
   echo "Shutting down..."
   if [ -f "/home/node/app/openclaw-sync.py" ] && [ -n "${HF_TOKEN:-}" ]; then
     echo "Saving state before exit..."
+    # BUG FIX: kill the background sync loop *before* running the shutdown
+    # syncs.  The loop holds the sync lock while uploading; if it is
+    # mid-upload when sync-once-settled runs, the 8-second timeout fires
+    # before the lock is released and the settled-sync is silently skipped.
+    # Killing the loop first releases the lock immediately (fcntl.flock is
+    # released on process exit) so sync-once-settled can acquire it cleanly.
+    if [ -n "${SYNC_LOOP_PID:-}" ]; then
+      kill "$SYNC_LOOP_PID" 2>/dev/null || true
+      # Give Python a moment to flush and release the lock file.
+      sleep 0.5
+    fi
     timeout 8s python3 /home/node/app/openclaw-sync.py sync-once-settled || \
       echo "Warning: could not complete settled shutdown sync"
     sleep 1
@@ -820,20 +948,24 @@ graceful_shutdown() {
 }
 trap graceful_shutdown SIGTERM SIGINT
 
+BROWSER_WARMED_UP=false
 warmup_browser() {
   [ "$BROWSER_SHOULD_ENABLE" = "true" ] || return 0
+  # Only warm up once — gateway restarts should not re-spawn new warmup jobs.
+  [ "$BROWSER_WARMED_UP" = "false" ] || return 0
+  BROWSER_WARMED_UP=true
 
   (
-    sleep 5
+    sleep 8
 
     local attempt
-    for attempt in 1 2 3 4 5; do
+    for attempt in 1 2 3 4 5 6; do
       if openclaw browser --browser-profile openclaw start >/dev/null 2>&1; then
         openclaw browser --browser-profile openclaw open about:blank >/dev/null 2>&1 || true
         echo "Managed browser ready."
         return 0
       fi
-      sleep 2
+      sleep 5
     done
 
     echo "Warning: managed browser warm-up did not complete; first browser action may need a retry."
@@ -843,6 +975,21 @@ warmup_browser() {
 
 # ── Start background services ──
 export LLM_MODEL="$LLM_MODEL"
+
+# ── Ensure key-rotator uses the correct HF token for huggingface.co calls ──
+# NODE_OPTIONS preloads multi-provider-key-rotator.cjs into health-server.js.
+# The rotator patches https.request and injects HUGGINGFACE_HUB_TOKEN (or
+# falls back to LLM_API_KEY) for any call to huggingface.co — including the
+# privacy-detection API call in detectSpacePrivacy(). If HUGGINGFACE_HUB_TOKEN
+# is not set (user's LLM provider is not HuggingFace), the rotator falls back
+# to LLM_API_KEY, which is the AI-provider key, NOT the HF owner token.
+# This causes a 401 on /api/spaces/${SPACE_ID} → privacy detection always
+# fails → SPACE_IS_PRIVATE stays true → public-space links never open in a
+# new tab.
+# Fix: seed HUGGINGFACE_HUB_TOKEN from HF_TOKEN when not already set.
+# HF Spaces auto-injects HF_TOKEN as the space owner's token, so this is safe.
+export HUGGINGFACE_HUB_TOKEN="${HUGGINGFACE_HUB_TOKEN:-${HF_TOKEN:-}}"
+
 # 10. Start Health Server & Dashboard
 node /home/node/app/health-server.js &
 HEALTH_PID=$!
@@ -885,6 +1032,11 @@ start_jupyter_once() {
       ln -sfn /home/node/.openclaw/workspace "$JUPYTER_ROOT_DIR/HuggingClaw-Workspace"
     fi
   fi
+  if [ "$JUPYTER_ROOT_DIR" != "/home/node/.openclaw" ]; then
+    if [ -L "$JUPYTER_ROOT_DIR/OpenClaw-Home" ] || [ ! -e "$JUPYTER_ROOT_DIR/OpenClaw-Home" ]; then
+      ln -sfn /home/node/.openclaw "$JUPYTER_ROOT_DIR/OpenClaw-Home"
+    fi
+  fi
 
   # Pre-create runtime directory
   mkdir -p "$JUPYTER_ROOT_DIR/.jupyter"
@@ -1248,7 +1400,7 @@ fi
 # Runs user-provided boot commands one by one so failures are visible in logs.
 # By default failures are logged and boot continues; set
 # HUGGINGCLAW_STARTUP_STRICT=true to fail the Space startup on any error.
-HC_STARTUP_FAILURES=0
+# HC_STARTUP_FAILURES initialized earlier (before Chromium ensure check)
 HC_STARTUP_STRICT_NORMALIZED=$(printf '%s' "${HUGGINGCLAW_STARTUP_STRICT:-false}" | tr '[:upper:]' '[:lower:]')
 hc_run_startup_command() {
   local source_label="$1"
@@ -1427,6 +1579,11 @@ if [ -n "${HUGGINGCLAW_OPENCLAW_PLUGINS:-}" ]; then
   fi
 fi
 
+# ── Fix config before running startup commands ──
+if [ "${AUTO_DOCTOR:-false}" = "true" ]; then
+  openclaw doctor --fix || true
+fi
+
 # ── Arbitrary startup commands from HF Variables/Secrets ──
 # Recommended: use one variable, HUGGINGCLAW_RUN, as a full bash script. If the
 # value starts with base64: or b64:, the rest is decoded and run as the script.
@@ -1543,6 +1700,16 @@ start_guardian_once() {
   echo "WhatsApp Guardian started (PID: $GUARDIAN_PID)"
 }
 
+# ── Start D-Bus session (once, before gateway loop) ──
+if [ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ]; then
+  if command -v dbus-launch >/dev/null 2>&1; then
+    eval "$(dbus-launch --sh-syntax 2>/dev/null)" || true
+    export DBUS_SESSION_BUS_ADDRESS="${DBUS_SESSION_BUS_ADDRESS:-disabled:}"
+  else
+    export DBUS_SESSION_BUS_ADDRESS="disabled:"
+  fi
+fi
+
 while true; do
   # Check health-server process - restart if died unexpectedly
   if [ -n "${HEALTH_PID:-}" ] && ! kill -0 "$HEALTH_PID" 2>/dev/null; then
@@ -1568,9 +1735,12 @@ while true; do
     fi
   fi
 
-  echo "Launching OpenClaw gateway on port 7860..."
+  if [ "${AUTO_DOCTOR:-false}" = "true" ]; then
+    openclaw doctor --fix || true
+  fi
+  echo "Launching OpenClaw gateway on port ${GATEWAY_PORT}..."
 
-  GATEWAY_ARGS=(gateway run --port 7860 --bind lan)
+  GATEWAY_ARGS=(gateway run --port "${GATEWAY_PORT}" --bind lan)
   if [ "${GATEWAY_VERBOSE:-0}" = "1" ]; then
     GATEWAY_ARGS+=(--verbose)
     echo "Gateway verbose logging enabled (GATEWAY_VERBOSE=1)"
@@ -1583,13 +1753,13 @@ while true; do
   stdbuf -oL -eL openclaw "${GATEWAY_ARGS[@]}" 2>&1 | tee -a /home/node/.openclaw/gateway.log &
   GATEWAY_PID=$!
 
-  # Poll for the gateway to start listening on 7860. OpenClaw can take 20-30s
+  # Poll for the gateway to start listening on ${GATEWAY_PORT}. OpenClaw can take 20-30s
   # on cold start (plugin install + auto-restore). Bail out early if the
   # pipeline died.
   GATEWAY_READY_TIMEOUT="${GATEWAY_READY_TIMEOUT:-90}"
   ready=false
   for ((i=0; i<GATEWAY_READY_TIMEOUT; i++)); do
-    if (echo > /dev/tcp/127.0.0.1/7860) 2>/dev/null; then
+    if (echo > /dev/tcp/127.0.0.1/${GATEWAY_PORT}) 2>/dev/null; then
       ready=true
       break
     fi
@@ -1604,7 +1774,14 @@ while true; do
     echo "Gateway failed to start. Last 30 lines of log:"
     echo "────────────────────────────────────────────"
     tail -30 /home/node/.openclaw/gateway.log
-    exit 1
+    if [ "$DEV_MODE_ENABLED" = "true" ]; then
+      echo "Gateway failed — DEV_MODE active, retrying in 10s..."
+      sleep 10
+      continue
+    else
+      echo "Gateway failed — exiting."
+      exit 1
+    fi
   fi
 
   # 11. Start WhatsApp Guardian after the gateway is accepting connections
@@ -1629,7 +1806,8 @@ while true; do
   GATEWAY_RESTART_COUNT=$((GATEWAY_RESTART_COUNT + 1))
   if [ "$GATEWAY_MAX_RESTARTS" != "0" ] && [ "$GATEWAY_RESTART_COUNT" -ge "$GATEWAY_MAX_RESTARTS" ]; then
     echo "Gateway exited with code ${GATEWAY_EXIT_CODE}; restart limit (${GATEWAY_MAX_RESTARTS}) reached."
-    exit "$GATEWAY_EXIT_CODE"
+    echo "Gateway stopped — JupyterLab and env-builder still running."
+    break
   fi
 
   echo "Gateway exited with code ${GATEWAY_EXIT_CODE}; restarting in ${GATEWAY_RESTART_DELAY}s..."

wa-guardian.js

@@ -17,7 +17,8 @@ try {
 }
 const { randomUUID } = require('node:crypto');
 
-const GATEWAY_URL = "ws://127.0.0.1:7860";
+const GATEWAY_PORT = Number.parseInt(process.env.GATEWAY_PORT || "7860", 10);
+const GATEWAY_URL = `ws://127.0.0.1:${GATEWAY_PORT}`;
 const GATEWAY_TOKEN = process.env.GATEWAY_TOKEN || "huggingclaw";
 const WHATSAPP_ENABLED = /^true$/i.test(process.env.WHATSAPP_ENABLED || "");
 const CHECK_INTERVAL = 30000;
@@ -91,7 +92,7 @@ async function createConnection() {
           method: "connect",
           params: {
             minProtocol: 3,
-            maxProtocol: 3,
+            maxProtocol: 4,
             client: {
               id: "gateway-client",
               version: "1.0.0",
@@ -125,7 +126,8 @@ async function createConnection() {
   });
 }
 
-async function callRpc(ws, method, params) {
+async function callRpc(ws, method, params, timeoutMs) {
+  const ms = timeoutMs !== undefined ? timeoutMs : 10000; // default 10s for normal calls
   return new Promise((resolve, reject) => {
     const id = randomUUID();
     const handler = (data) => {
@@ -148,7 +150,7 @@ async function callRpc(ws, method, params) {
       reject(sendErr);
       return;
     }
-    setTimeout(() => { ws.removeListener("message", handler); reject(new Error("RPC Timeout")); }, WAIT_TIMEOUT + 5000);
+    setTimeout(() => { ws.removeListener("message", handler); reject(new Error("RPC Timeout")); }, ms);
   });
 }
 
@@ -188,7 +190,7 @@ async function checkStatus() {
     }
 
     console.log("[guardian] Waiting for pairing completion...");
-    const waitRes = await callRpc(ws, "web.login.wait", { timeoutMs: WAIT_TIMEOUT });
+    const waitRes = await callRpc(ws, "web.login.wait", { timeoutMs: WAIT_TIMEOUT }, WAIT_TIMEOUT + 5000);
     const result = waitRes.payload || waitRes.result;
     const message = result?.message || "";
     const linkedAfter515 = !result?.connected && message.includes("515");
@@ -202,19 +204,27 @@ async function checkStatus() {
       lastConnectedAt = Date.now();
       writeStatus({ configured: true, connected: true, pairing: false });
 
+      // Set shouldStop BEFORE config.apply — gateway restart during apply must not
+      // leave guardian running (it would then incorrectly wipe valid credentials).
+      shouldStop = true;
+
       if (linkedAfter515) {
         console.log("[guardian] 515 after scan: credentials saved, reloading config to start WhatsApp...");
       } else {
         console.log("[guardian] Pairing completed! Reloading config...");
       }
 
-      const getRes = await callRpc(ws, "config.get", {});
-      if (getRes.payload?.raw && getRes.payload?.hash) {
-        await callRpc(ws, "config.apply", { raw: getRes.payload.raw, baseHash: getRes.payload.hash });
-        console.log("[guardian] Configuration re-applied.");
+      try {
+        const getRes = await callRpc(ws, "config.get", {});
+        if (getRes.payload?.raw && getRes.payload?.hash) {
+          await callRpc(ws, "config.apply", { raw: getRes.payload.raw, baseHash: getRes.payload.hash });
+          console.log("[guardian] Configuration re-applied.");
+        }
+      } catch (applyErr) {
+        // Gateway restarted during config.apply — that is expected and fine.
+        // shouldStop is already true so we will not retry or attempt logout.
+        console.log(`[guardian] Config re-apply interrupted (gateway restarting): ${applyErr.message}`);
       }
-
-      shouldStop = true;
       setTimeout(() => process.exit(0), 1000);
     } else if (!message.includes("No active") && !message.includes("Still waiting")) {
       console.log(`[guardian] Wait result: ${message}`);