@flame0510/project-aether 1.2.0 → 1.4.0

package/app/api/agents/models-summary/route.ts

@@ -0,0 +1,163 @@
+/**
+ * GET /api/agents/models-summary
+ *
+ * One row per agent, running or not: which model it runs, and whether that model is in
+ * good standing. Feeds the model chip on the agent cards, so the list answers
+ * "what is this agent running, and is it fine?" without opening anything.
+ *
+ * That question had no cheap answer before: the model lived only inside each
+ * container's config, and the only route that read it walked the whole fleet.
+ * Three agents silently moved to DeepSeek V4.1, and one has been pointing at a
+ * model absent from its own catalogue, precisely because nothing surfaced it.
+ *
+ * Fan-out uses the NoFail variants: one unreachable container must degrade its
+ * own row, not blank the page. `mapWithConcurrency` is fail-fast, so a throwing
+ * mapper would discard every result already computed.
+ */
+import { NextResponse } from 'next/server';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { dockerExecNoFail, mapWithConcurrency } from '@/lib/docker-exec';
+import { loadModelsConfig, loadOfferedModels } from '@/lib/model-catalogue';
+import { singleFileFromTar } from '@/lib/container-file';
+import { requireAuthJWT } from '@/lib/rev4a-auth';
+
+const execFileAsync = promisify(execFile);
+
+export const dynamic = 'force-dynamic';
+
+/** Matches the per-agent query cap used elsewhere for fleet walks. */
+const CONCURRENCY = 6;
+
+const CONFIG_PATH = '/root/.openclaw/openclaw.json';
+
+/** A not-running agent's config, through `docker cp`. Empty string when unreadable. */
+async function readNotRunningConfig(container: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync('docker', ['cp', `${container}:${CONFIG_PATH}`, '-'], {
+      encoding: 'buffer', timeout: 8000, maxBuffer: 1024 * 1024,
+    });
+    return singleFileFromTar(stdout as unknown as Buffer).body.toString('utf-8');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * - `missing`     the primary is not in the catalogue at all
+ * - `disabled`    in the catalogue but not offered: unchecked, or its provider has no key
+ * - `out-of-sync` offered by the gateway, absent from this container's synced copy
+ * - `deprecated`  works, on a name upstream has retired
+ */
+export type ModelHealth = 'ok' | 'deprecated' | 'missing' | 'disabled' | 'out-of-sync' | 'unset' | 'unknown';
+
+export interface AgentModelRow {
+  agentId: string;
+  containerName: string;
+  primary: string | null;
+  fallbackCount: number;
+  /** First fallback, for the one-line hint on the card. The rest stay in the panel. */
+  firstFallback: string | null;
+  health: ModelHealth;
+}
+
+export async function GET(request: Request): Promise<NextResponse> {
+  const denied = await requireAuthJWT(request);
+  if (denied) return denied as any;
+
+  let agents: { agentId: string; containerName: string; running: boolean }[] = [];
+  try {
+    // `-a`: a stopped agent is the likeliest to be sitting on a model that has
+    // since been removed or disabled, and it needs a chip as much as any.
+    const { stdout } = await execFileAsync(
+      'docker',
+      ['ps', '-a', '--filter', 'label=AGENT_ID', '--format', '{{.Label "AGENT_ID"}}\t{{.Names}}\t{{.State}}'],
+      { encoding: 'utf8', timeout: 5000 },
+    );
+    agents = stdout.trim().split('\n')
+      .map((line) => {
+        const [agentId, containerName, state] = line.split('\t');
+        if (!containerName?.trim()) return null;
+        return {
+          agentId: agentId?.trim() || containerName.trim(),
+          containerName: containerName.trim(),
+          running: state?.trim() === 'running',
+        };
+      })
+      .filter(Boolean) as { agentId: string; containerName: string; running: boolean }[];
+  } catch (e) {
+    // Not an empty list: that reads as "every agent is fine".
+    return NextResponse.json(
+      { agents: [], error: `Docker is unreachable: ${(e as Error).message.split('\n')[0]}` },
+      { status: 503 },
+    );
+  }
+
+  if (agents.length === 0) return NextResponse.json({ agents: [] });
+
+  // Deprecation is a property of the catalogue, not of the container: read it once.
+  const catalogue = new Map(loadModelsConfig().map((m) => [m.id, m]));
+  // What the gateway will actually serve. The proxy refuses anything outside it,
+  // so this set, not the container's copy, decides whether an agent can work.
+  const offered = new Set(loadOfferedModels().map((m) => m.id));
+
+  const rows = await mapWithConcurrency(agents, CONCURRENCY, async (agent): Promise<AgentModelRow> => {
+    const base: AgentModelRow = {
+      agentId: agent.agentId,
+      containerName: agent.containerName,
+      primary: null,
+      fallbackCount: 0,
+      firstFallback: null,
+      health: 'unknown',
+    };
+
+    const raw = agent.running
+      ? await dockerExecNoFail(agent.containerName, ['cat', CONFIG_PATH], { timeoutMs: 8000 })
+      : await readNotRunningConfig(agent.containerName);
+    // An empty body means unreachable *or* a read killed by the deadline —
+    // `docker exec` exits 0 either way, so both stay 'unknown' rather than
+    // being reported as a healthy agent with no model.
+    if (!raw) return base;
+
+    let config: Record<string, unknown>;
+    try { config = JSON.parse(raw); } catch { return base; }
+
+    const defaults = ((config.agents ?? {}) as Record<string, unknown>).defaults ?? {};
+    const model = (defaults as Record<string, unknown>).model;
+    const primary = typeof model === 'string'
+      ? model
+      : (model && typeof model === 'object' ? (model as Record<string, unknown>).primary : null);
+    const fallbacks = model && typeof model === 'object' && Array.isArray((model as Record<string, unknown>).fallbacks)
+      ? ((model as Record<string, unknown>).fallbacks as unknown[])
+      : [];
+
+    if (typeof primary !== 'string' || !primary) return { ...base, health: 'unset' };
+
+    const bare = primary.replace(/^rev4a\//, '');
+    const models = ((config.models ?? {}) as Record<string, unknown>).providers ?? {};
+    const rev4a = ((models as Record<string, unknown>).rev4a ?? {}) as Record<string, unknown>;
+    const ids = (Array.isArray(rev4a.models) ? rev4a.models : [])
+      .map((m) => (m && typeof m === 'object' ? (m as Record<string, unknown>).id : null))
+      .filter((id): id is string => typeof id === 'string');
+
+    const entry = catalogue.get(bare);
+    let health: ModelHealth;
+    // Ordered by remedy. Each case asks something different of the operator, and
+    // the single 'missing' this replaced pointed at the wrong fix half the time.
+    if (!entry) health = 'missing';                       // gone from the catalogue: pick another model
+    else if (!offered.has(bare)) health = 'disabled';     // exists, not offered: the proxy refuses it
+    else if (!ids.includes(bare)) health = 'out-of-sync'; // offered, never reached this container: Sync All
+    else if (entry.deprecated) health = 'deprecated';     // works, on a retired name
+    else health = 'ok';
+
+    return {
+      ...base,
+      primary,
+      fallbackCount: fallbacks.length,
+      firstFallback: typeof fallbacks[0] === 'string' ? (fallbacks[0] as string) : null,
+      health,
+    };
+  });
+
+  return NextResponse.json({ agents: rows });
+}

package/app/api/agents/route.ts

@@ -1,9 +1,8 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import * as fs from 'fs';
-import * as path from 'path';
-import { AGENTS_TOKEN_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 import { dockerAvailable, dockerFetch } from '@/lib/docker-socket';
+import { containerOpenClawVersion, listLocalAgentImages, newestLocalSupportedVersion, type LocalAgentImage } from '@/lib/agent-images';
+import { LOCAL_IMAGE_REPOSITORY, compareVersions } from '@/lib/agent-versions';
 
 export const dynamic = 'force-dynamic';
 
@@ -21,14 +20,15 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
       '/containers/json?all=true&filters={"label":["AGENT_ID"]}',
     );
 
-    // Current image ID — used to detect outdated containers
-    let currentImageId = '';
+    // Local agent images: each container's OpenClaw version, and the newest supported
+    // version downloaded, which decides `updateAvailable`.
+    let images: LocalAgentImage[] = [];
     try {
-      const imageInspect = await dockerFetch('GET', '/images/openclaw-agent-base:latest/json');
-      currentImageId = imageInspect.Id || '';
+      images = await listLocalAgentImages();
     } catch {
-      // Image doesn't exist yet — all containers are fine
+      // No image list: versions come from inside running containers only.
     }
+    const newestLocal = newestLocalSupportedVersion(images);
 
     const agents = await Promise.all(
       containers.map(async (c: any) => {
@@ -36,7 +36,6 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         let ip: string | null = null;
         let created: string | null = null;
         let env: string[] = [];
-        let authToken: string | null = null;
         let controlPort: string | null = null;
         let portBindings: Record<string, Array<{ HostIp: string; HostPort: string }>> | null = null;
 
@@ -59,42 +58,9 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
           // Ports from inspect (HostConfig) — works even when container is stopped
           portBindings = inspect.HostConfig?.PortBindings || null;
 
-          // Read auth token — always prefer the shared agents-token.json (user-managed)
-          try {
-            const tokenRaw = fs.readFileSync(
-              AGENTS_TOKEN_FILE,
-              'utf-8'
-            );
-            const tokenData = JSON.parse(tokenRaw);
-            if (tokenData.token) {
-              authToken = tokenData.token;
-            }
-          } catch {
-            // agents-token.json unavailable
-          }
-
-          // Fallback when the shared file is missing: the container's own token,
-          // taken from the inspect data already fetched above.
-          //
-          // This used to `docker exec … grep OPENCLAW_GATEWAY_TOKEN /root/….env`
-          // — a path containing a literal U+2026 ellipsis, so not a path at all.
-          // Correcting the character wouldn't have helped: agent containers have
-          // no .env file, and no file under /root/ holds that variable (verified
-          // across the production fleet). The token exists only in the container
-          // environment, which is right here in Config.Env. So the fallback spawned
-          // a blocking process per agent to read a file that cannot exist, failed
-          // silently, and left every "Open" button without its token — while the
-          // value sat in memory, already fetched.
-          if (!authToken) {
-            const fromEnv = ((inspect.Config?.Env || []) as string[])
-              .find((e) => e.startsWith('OPENCLAW_GATEWAY_TOKEN='));
-            const token = fromEnv?.slice('OPENCLAW_GATEWAY_TOKEN='.length).trim();
-            if (token && token !== 'undefined') authToken = token;
-          }
-
           // The host port mapped to the agent's Control UI (container port 3000).
-          // Only the port is returned: the browser composes the full URL, because
-          // only the browser knows which hostname actually reaches this machine.
+          // No link and no token are returned: the Open buttons go through
+          // /api/agents/[id]/open-control-ui, which builds the link server-side.
           // Read from portBindings (works on a stopped container) with a fallback
           // to c.Ports, which is only populated while running.
           const port3000Binding = portBindings?.['3000/tcp'];
@@ -109,7 +75,17 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
         // Falls back to 'custom' if not set (agent created before this feature).
         const image: string = c.Image || '';
         let template: string | null = null;
-        if (image.startsWith('openclaw-agent-base')) {
+        // Every container here carries AGENT_ID, so its version is looked up even when
+        // its image is not tagged `openclaw-agent-base` (an image left untagged, or
+        // pinned by id). The image name alone would miss those.
+        const openclawVersion = await containerOpenClawVersion(
+          { name: (c.Names?.[0] || '').replace(/^\//, ''), imageId: c.ImageID || '', running: c.State === 'running' },
+          images,
+        );
+        const isAgentBase = image.startsWith(LOCAL_IMAGE_REPOSITORY)
+          || images.some((img) => img.id === c.ImageID)
+          || openclawVersion !== null;
+        if (isAgentBase) {
           const templateLine = env.find((e: string) => e.startsWith('AGENT_TEMPLATE='));
           template = templateLine ? templateLine.split('=').slice(1).join('=') : 'custom';
         }
@@ -147,10 +123,10 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
           created,
           env,
           controlPort,
-          authToken,
-          // Flag as outdated when the container's image differs from the current base image.
-          // We compare raw ImageID digests — no fragile name-based filtering.
-          imageOutdated: currentImageId ? c.ImageID !== currentImageId : false,
+          openclawVersion,
+          // A newer supported OpenClaw version is downloaded. Recreate keeps the agent's
+          // version; moving to the newer one is a separate, backed-up update.
+          updateAvailable: !!(openclawVersion && newestLocal && compareVersions(newestLocal, openclawVersion) > 0),
         };
       }),
     );

package/app/api/agents/token/route.ts

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import { NextResponse, type NextRequest } from 'next/server';
 import { AGENTS_TOKEN_FILE } from '@/lib/rev4a-paths';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { agentBusyReason } from '@/lib/agent-busy';
 
 export const dynamic = 'force-dynamic';
 
@@ -57,37 +58,59 @@ export async function PUT(request: NextRequest): Promise<NextResponse> {
     fs.writeFileSync(AGENTS_TOKEN_FILE, JSON.stringify(payload, null, 2));
 
     let containersUpdated = 0;
-    let containerNames: string[] = [];
+    /** Containers left alone because an operation is running on them. */
+    const skipped: string[] = [];
+    /** Containers that could not be updated, with the reason. */
+    const failed: { container: string; error: string }[] = [];
+    let containers: { name: string; agentId: string }[] = [];
 
     try {
       const raw = execSync(
-        `docker ps --filter "label=AGENT_ID" --format "{{.Names}}"`,
+        `docker ps --filter "label=AGENT_ID" --format '{{.Names}} {{.Label "AGENT_ID"}}'`,
         { encoding: 'utf-8', timeout: 5000 },
       ).trim();
-      containerNames = raw ? raw.split('\n').map((name) => name.trim()).filter(Boolean) : [];
+      containers = raw
+        ? raw.split('\n').map((line) => {
+          const [name, agentId] = line.trim().split(/\s+/);
+          return { name: (name ?? '').trim(), agentId: (agentId ?? '').trim() };
+        }).filter((c) => c.name)
+        : [];
     } catch {
-      containerNames = [];
+      containers = [];
     }
 
-    for (const containerName of containerNames) {
+    for (const { name, agentId } of containers) {
       try {
+        // Restarting an agent mid-update, mid-recreate, mid-restore or mid-edit would cut
+        // the operation in half: leave it and say so.
+        if (agentId && (await agentBusyReason(agentId))) {
+          skipped.push(name);
+          continue;
+        }
         // Write token to /root/.agent-token (entrypoint reads this, overrides env var)
         execSync(
-          `docker exec ${shellQuote(containerName)} sh -c 'echo ${shellQuote(token)} > /root/.agent-token'`,
+          `docker exec ${shellQuote(name)} sh -c 'echo ${shellQuote(token)} > /root/.agent-token'`,
           { encoding: 'utf-8', timeout: 10000 },
         );
         // Restart to pick up new token
-        execSync(`docker restart ${shellQuote(containerName)}`, {
+        execSync(`docker restart ${shellQuote(name)}`, {
           encoding: 'utf-8',
           timeout: 20000,
         });
         containersUpdated += 1;
-      } catch {
-        // Skip failed containers and continue syncing the rest.
+      } catch (e) {
+        // Report the failure instead of swallowing it: a token that reached only some
+        // agents used to look like a full success.
+        failed.push({ container: name, error: (e as Error)?.message ?? String(e) });
       }
     }
 
-    return NextResponse.json({ success: true, containersUpdated });
+    return NextResponse.json({
+      success: failed.length === 0,
+      containersUpdated,
+      ...(skipped.length ? { skipped } : {}),
+      ...(failed.length ? { failed } : {}),
+    });
   } catch (e: unknown) {
     return NextResponse.json(
       { success: false, error: (e as Error).message || 'Unknown error' },

package/app/api/assistant/route.ts

@@ -2,8 +2,11 @@ import { NextResponse, type NextRequest } from 'next/server';
 import { readProviderKeys } from '@/app/api/gateway/provider/keys';
 import { extractProviderAndModel, getApiKey, callUpstream } from '@/app/api/provider/upstream';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
+import { isModelOffered, loadOfferedModels } from '@/lib/model-catalogue';
 
-const FALLBACK_MODEL = 'deepseek/deepseek-v4-flash';
+// DeepSeek Flash (V4.1). Used only when the client names no model, and refused
+// like any other if it has been unchecked on the Gateway page.
+const FALLBACK_MODEL = 'deepseek/deepseek-flash';
 
 interface PageContext {
   title: string;
@@ -15,27 +18,27 @@ interface PageContext {
 const PAGE_CONTEXT: Record<string, PageContext> = {
   '/': {
     title: 'Dashboard',
-    description: 'Main overview with live session list, cost summary (today, 7 days, 30 days by model), system health metrics (CPU, RAM, disk, load), and a real-time event feed.',
+    description: 'Main overview with live session list, cost summary by model, health cards for Rev4a\'s own runtime, cron and lineage, and a real-time event feed. It shows no CPU, RAM, disk or load average: those are collected by the daemon but no page displays them.',
     actions: ['Click any session row to open the Session Drawer for full details and tool call history', 'View cost breakdown by model and time period', 'See live events as they happen', 'Take a screenshot of the dashboard (mobile)'],
     hints: 'The Session Drawer shows you the complete tool call history for any session — just click a row.',
   },
   '/agents': {
     title: 'Agents',
     description: 'List of all Docker containers that run OpenClaw agents. Shows status (running/exited/paused), image, ports, IP, and creation time. Includes a top banner for the agent base image status: yellow warning when outdated or missing, animated progress bar when downloading from registry.',
-    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, auth token, Traefik URL)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
-    hints: 'The status bullet tells you at a glance if an agent is running (green), exited (red), or paused (yellow). The base image banner shows when an updated version is available on the registry — download to pick up CLI updates.',
+    actions: ['Filter by status: all, running, or exited', 'Click an agent to see its details (environment variables, backups, Telegram channels, and the Model section that sets its primary model and fallbacks)', 'Create a new agent using the "Create Agent" button', 'Download the agent base image when the banner shows it missing or outdated'],
+    hints: 'The status bullet tells you at a glance if an agent is running (green), exited (red), or paused (yellow). The base image banner shows when a newer supported version is published on the registry — downloading makes it available to create and update agents on; it changes no agent by itself.',
   },
   '/agents/create': {
     title: 'Create Agent',
-    description: 'Wizard to create a new agent from a template. Choose a template, give it a name, select a model, set environment variables, and configure optional Traefik routing.',
-    actions: ['Browse available agent templates', 'Name your agent and select its AI model', 'Add environment variables (KEY=*** pairs)', 'Optionally enable Traefik routing with a custom subdomain', 'Create the agent and start it immediately'],
-    hints: 'Templates provide pre-built agent configurations. You can customize the image, model, and env vars after selecting a template.',
+    description: 'Two-step wizard to create a new agent from a template. Pick a template, then name it and optionally set a port range and a model.',
+    actions: ['Browse available agent templates', 'Name your agent and select its AI model', 'Set an optional port range (auto-assigned by default)', 'Create the agent and start it immediately'],
+    hints: 'Templates provide pre-built agent configurations. The model can be changed later from the agent\'s detail panel on the Agents page.',
   },
   '/gateway': {
     title: 'Gateway',
-    description: 'Central gateway management page. Shows OpenClaw gateway status, all configured AI providers with their models, and each agent\'s model assignment with fallback models.',
-    actions: ['Toggle models on/off per provider to control availability', 'View which model each agent uses as default', 'See fallback models configured for each agent', 'Check gateway health status and last sync time', 'Sync providers from the gateway configuration'],
-    hints: 'The Gateway is the routing layer that connects agents to AI providers. Use this page to manage which models agents can access.',
+    description: 'Provider configuration: API keys, and which catalogue models this deployment offers. It does not assign models to agents.',
+    actions: ['Add, change or remove a provider API key', 'Toggle individual models on or off to control what the fleet is offered', 'Push the resulting catalogue to every agent container with Sync All Agents'],
+    hints: 'Unchecking a model here removes it everywhere, including for requests that name it directly. To change which model one agent runs, open that agent on the Agents page and use the Model section.',
   },
   '/crons': {
     title: 'Crons',
@@ -45,8 +48,8 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   },
   '/containers': {
     title: 'Containers',
-    description: 'List of all Docker containers running on the server (not just agents). Shows container ID, name, image, status, state, ports, and IP address.',
-    actions: ['View all running containers with their details', 'Click "Terminal" on any container to open an interactive shell', 'Monitor container status and resource usage'],
+    description: 'List of all Docker containers on the server, running or stopped (not just agents). Shows container ID, name, image, status, state, ports, and IP address.',
+    actions: ['View every container, running or stopped, with its details', 'Click "Terminal" on any container to open an interactive shell', 'Check each container\'s status, image, IP and ports (no CPU or memory figures are shown)'],
     hints: 'Containers marked with an agentId belong to OpenClaw agents. Others are infrastructure containers like databases or reverse proxies.',
   },
   '/containers/terminal/[id]': {
@@ -64,7 +67,7 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   '/lineage': {
     title: 'Lineage',
     description: 'Interactive graph showing parent-child relationships between agent sessions. Each node is a session, edges show who spawned whom.',
-    actions: ['View the session hierarchy tree', 'Select a time period (1d/7d/30d) to filter the view', 'Click any session node to inspect its details', 'Zoom and pan through the graph'],
+    actions: ['View the session hierarchy tree', 'Select a time period (1d, 3d, 7d, 15d, 30d or all) to filter the view', 'Click any session node to inspect its details', 'Zoom and pan through the graph'],
     hints: 'When an agent spawns a child agent to do work, that relationship is shown here. Use the period selector to see recent activity.',
   },
   '/memory': {
@@ -81,9 +84,9 @@ const PAGE_CONTEXT: Record<string, PageContext> = {
   },
   '/tools': {
     title: 'Tools',
-    description: 'Catalog of all tools available to agents — built-in tools, MCP (Model Context Protocol) tools, plugin tools, and audio transcription tools.',
-    actions: ['Browse the full tool catalog', 'See tool name, source package, and description', 'View audio/voice configuration settings', 'Check which MCP servers are connected'],
-    hints: 'Each tool has a source (built-in, plugin, or MCP server). If a tool is missing, check the relevant plugin or MCP connection.',
+    description: 'Curated catalog of the OpenClaw built-in tools available to agents, grouped by area, plus audio and timezone settings. It does not list MCP servers or plugin tools.',
+    actions: ['Browse the full tool catalog', 'See each tool\'s name, description and status (Configured, Available, Coming soon)', 'View the audio transcription and time zone settings'],
+    hints: 'The catalog is a fixed list of OpenClaw built-in tools, not read from the agents. It shows no MCP servers or plugin tools, so a tool missing here says nothing about what an agent has.',
   },
   '/plugins': {
     title: 'Plugins',
@@ -177,6 +180,24 @@ export async function POST(request: NextRequest): Promise<Response> {
   ];
 
   const { provider, model: upstreamModel } = extractProviderAndModel({ model: effectiveModel });
+
+  // The chat panel loads its model list once, at mount, and keeps the choice in
+  // localStorage — so it can name a model that was unchecked on the Gateway page
+  // an hour ago, or one already gone when the preference was saved. Enforce the
+  // catalogue here rather than trusting the client to hold a current list.
+  if (!isModelOffered(provider, upstreamModel)) {
+    const alternative = loadOfferedModels()[0];
+    return NextResponse.json(
+      {
+        error: `Model '${provider}/${upstreamModel}' is not enabled for this deployment.`
+             + (alternative
+                 ? ` Try ${alternative.id}, or enable it on the Gateway page.`
+                 : ' No model is currently enabled — check the Gateway page.'),
+      },
+      { status: 400 },
+    );
+  }
+
   const providerKeys = readProviderKeys();
   const apiKey = getApiKey(provider, providerKeys);
 

package/app/api/gateway/agent/route.ts

@@ -5,9 +5,10 @@
  * Uses base64-safe write — no heredoc shell escaping issues.
  *
  * Body:
- *   { "containerName": "openclaw-atlas", "model": "rev4a/deepseek-v4-flash", "fallbacks": ["rev4a/deepseek-v4-pro"] }
+ *   { "containerName": "openclaw-atlas", "model": "rev4a/deepseek-flash", "fallbacks": ["rev4a/deepseek-v4-pro"] }
  */
 import { NextRequest, NextResponse } from 'next/server';
+import { agentBusyReason } from '@/lib/agent-busy';
 import { execSync } from 'child_process';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
@@ -56,6 +57,21 @@ function readFileFromContainer(container: string, remotePath: string): string {
   }
 }
 
+/**
+ * Fallbacks already on a model entry, for a request that did not send any.
+ *
+ * `fallbacks` omitted and `fallbacks: []` are different requests. The first means
+ * "leave them alone", the second "clear them". This route used to treat both as
+ * `[]`, so any caller that sent only `model` silently erased the list.
+ */
+function existingFallbacks(model: unknown): string[] {
+  if (model && typeof model === 'object') {
+    const f = (model as { fallbacks?: unknown }).fallbacks;
+    if (Array.isArray(f)) return f.filter((x): x is string => typeof x === 'string');
+  }
+  return [];
+}
+
 export async function PUT(request: NextRequest) {
   const denied = await requireAuthJWT(request); if (denied) return denied as any;
   try {
@@ -75,6 +91,19 @@ export async function PUT(request: NextRequest) {
       return NextResponse.json({ status: 'error', error: 'model is required' }, { status: 400 });
     }
 
+    // Refuse while a long operation is running on this agent: the write would race the
+    // recreate/migration that is replacing the container underneath it.
+    try {
+      const agentId = execSync(
+        `docker inspect --format '{{index .Config.Labels "AGENT_ID"}}' ${safeContainer}`,
+        { encoding: 'utf-8', timeout: 5000 },
+      ).trim();
+      if (agentId) {
+        const busy = await agentBusyReason(agentId);
+        if (busy) return NextResponse.json({ status: 'error', error: busy }, { status: 409 });
+      }
+    } catch { /* no container or no label: the rest of the route reports it */ }
+
     // Read current config
     const raw = readFileFromContainer(safeContainer, '/root/.openclaw/openclaw.json');
     if (!raw) {
@@ -99,8 +128,8 @@ export async function PUT(request: NextRequest) {
     const mainAgent = list.find((a) => a.id === 'main');
     if (mainAgent) {
       const primary = ensureRev4aPrefix(body.model);
-      let fallbacks = dedupe(ensureRev4aPrefixes(body.fallbacks || []));
-      // Remove the primary model dai fallback
+      let fallbacks = dedupe(ensureRev4aPrefixes(body.fallbacks ?? existingFallbacks(mainAgent.model)));
+      // The primary never doubles as its own fallback.
       fallbacks = fallbacks.filter((fb) => fb !== primary);
       mainAgent.model = {
         primary,
@@ -111,7 +140,7 @@ export async function PUT(request: NextRequest) {
     const defaults = (agents.defaults || {}) as Record<string, unknown>;
     {
       const primary = ensureRev4aPrefix(body.model);
-      let fallbacks = dedupe(ensureRev4aPrefixes(body.fallbacks || []));
+      let fallbacks = dedupe(ensureRev4aPrefixes(body.fallbacks ?? existingFallbacks(defaults.model)));
       fallbacks = fallbacks.filter((fb) => fb !== primary);
       defaults.model = {
         primary,
@@ -144,8 +173,10 @@ export async function PUT(request: NextRequest) {
       status: 'ok',
       agent: safeContainer,
       model: {
-        primary: body.model,
-        fallbacks: body.fallbacks || [],
+        // Report what was written, not what was asked: both prefixed, and the
+        // fallbacks as preserved or replaced.
+        primary: (defaults.model as { primary: string }).primary,
+        fallbacks: (defaults.model as { fallbacks: string[] }).fallbacks,
       },
       verify: { ok: verifyOk, bytes: verifyBytes },
     });

package/app/api/gateway/provider/balance/route.ts

@@ -7,7 +7,7 @@
  * Supported providers: deepseek, openrouter, glm
  */
 import { NextRequest, NextResponse } from 'next/server';
-import { fetchProviderBalance, type BalanceProvider } from '@/lib/provider-balance';
+import { fetchProviderBalance, BalanceUnsupportedError, type BalanceProvider } from '@/lib/provider-balance';
 import { requireAuthJWT } from '@/lib/rev4a-auth';
 
 export const dynamic = 'force-dynamic';
@@ -33,6 +33,9 @@ export async function GET(request: NextRequest): Promise<NextResponse> {
     return NextResponse.json({ provider, ...result });
   } catch (e: unknown) {
     const message = e instanceof Error ? e.message : String(e);
-    return NextResponse.json({ provider, error: message }, { status: 502 });
+    // A permanent "no balance API for this account" is reported distinctly, so
+    // the UI can hide the badge instead of offering a retry that never works.
+    const reason = e instanceof BalanceUnsupportedError ? 'no-balance-api' : undefined;
+    return NextResponse.json({ provider, error: message, ...(reason && { reason }) }, { status: 502 });
   }
 }

package/app/api/gateway/provider/keys.ts

@@ -15,8 +15,16 @@ function ensureDir(): void {
   }
 }
 
+/** Best-effort: files written before 0600 was enforced are world-readable. */
+function tightenMode(): void {
+  try {
+    if ((fs.statSync(KEYS_PATH).mode & 0o077) !== 0) fs.chmodSync(KEYS_PATH, 0o600);
+  } catch { /* absent, or not ours to change */ }
+}
+
 export function readProviderKeys(): ProviderKeys {
   ensureDir();
+  tightenMode();
   try {
     const raw = fs.readFileSync(KEYS_PATH, 'utf-8');
     return JSON.parse(raw);
@@ -34,5 +42,9 @@ export function readProviderKeys(): ProviderKeys {
 
 export function writeProviderKeys(keys: ProviderKeys): void {
   ensureDir();
-  fs.writeFileSync(KEYS_PATH, JSON.stringify(keys, null, 2), 'utf-8');
+  // Every upstream credential and the gateway password live here: owner-only, like
+  // the .env file. `mode` applies only when the file is created, so an existing
+  // file is tightened explicitly.
+  fs.writeFileSync(KEYS_PATH, JSON.stringify(keys, null, 2), { encoding: 'utf-8', mode: 0o600 });
+  fs.chmodSync(KEYS_PATH, 0o600);
 }