@flame0510/project-aether 1.2.0 → 1.3.0

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

@@ -5,7 +5,7 @@
  * 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 { execSync } from 'child_process';
@@ -56,6 +56,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 {
@@ -99,8 +114,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 +126,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 +159,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/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);
 }

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

@@ -8,7 +8,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { execSync } from 'child_process';
 import { readProviderKeys, writeProviderKeys } from './keys';
-import { syncAllAgents } from '../sync';
+import { dockerUnreachableReason, syncAllAgents, type SyncOutcome } from '../sync';
 import { detectProviderGatewayUrl } from '@/lib/docker-utils';
 import { getPricing } from '@/lib/model-pricing';
 import { loadModelsConfig, toggleModelOverride, type ModelConfigEntry } from '@/lib/model-catalogue';
@@ -192,6 +192,20 @@ export async function GET(request: NextRequest) {
   return NextResponse.json({ providers });
 }
 
+/**
+ * Run the sync without letting an unexpected throw turn a committed change into a
+ * 500. `syncAllAgents` already reports Docker and per-container failures as data;
+ * this only guards the rest.
+ */
+function runSync(): SyncOutcome {
+  try {
+    return syncAllAgents();
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, activeModels: 0, total: 0, synced: [], stopped: [], failed: [], configError: msg, summary: `Not applied to any agent: ${msg}.` };
+  }
+}
+
 export async function POST(request: NextRequest) {
   const denied = await requireAuthJWT(request);
   if (denied) return denied;
@@ -199,8 +213,12 @@ export async function POST(request: NextRequest) {
     const body: { provider?: string; apiKey?: string; _syncOnly?: boolean } = await request.json();
 
     if (body._syncOnly) {
-      const syncResults = syncAllAgents();
-      return NextResponse.json({ status: 'ok', sync: syncResults });
+      // Here the sync *is* the operation, so its outcome is the status.
+      const sync = runSync();
+      return NextResponse.json(
+        sync.ok ? { status: 'ok', sync } : { status: 'error', error: sync.summary, sync },
+        { status: sync.ok ? 200 : 502 },
+      );
     }
 
     const providerName = body.provider;
@@ -210,15 +228,11 @@ export async function POST(request: NextRequest) {
     const apiKeyValue = body.apiKey;
     const isRemove = !apiKeyValue || apiKeyValue.trim() === '';
     setProviderApiKey(providerName, isRemove ? null : apiKeyValue!.trim());
-    let syncResults: string[] = [];
-    try {
-      syncResults = syncAllAgents();
-    } catch (se) {
-      syncResults = [`Sync error: ${se instanceof Error ? se.message : String(se)}`];
-    }
+    // The key is saved whatever the sync does next; report the two separately.
+    const sync = runSync();
     return NextResponse.json({
       status: 'ok', provider: providerName, configured: !isRemove,
-      sync: syncResults,
+      sync,
     });
   } catch (e: unknown) {
     return NextResponse.json({ status: 'error', error: e instanceof Error ? e.message : String(e) }, { status: 500 });
@@ -238,9 +252,26 @@ export async function PUT(request: NextRequest) {
     const idx = models.findIndex((m) => m.id === modelId);
     if (idx === -1) return NextResponse.json({ status: 'error', error: `Model not found: ${modelId}` }, { status: 404 });
 
+    // Refuse up front when the sync cannot happen at all. Saving anyway would leave
+    // the checkbox on /gateway saying one thing and every agent holding another.
+    // Only a whole-fleet outage is refused this way: once Docker answers, a container
+    // that fails individually is reported in `sync`, because undoing the override
+    // would not undo the containers that did receive it. Provider key saves are not
+    // gated like this — the first-run wizard saves keys without reading the response
+    // and may run before Docker is up, so a refusal there would be silent.
+    const unreachable = dockerUnreachableReason();
+    if (unreachable) {
+      return NextResponse.json({
+        status: 'error',
+        error: `Not changed: Docker is unreachable (${unreachable}). Nothing was saved, so the Gateway still matches the agents.`,
+      }, { status: 503 });
+    }
+
     toggleModelOverride(modelId, enabled);
-    const syncResults = syncAllAgents();
-    return NextResponse.json({ status: 'ok', modelId, enabled, provider: models[idx].provider, sync: syncResults });
+    // `status` is the toggle, committed at this point. `sync` is whether the fleet
+    // got it — reported alongside, not folded into `status`.
+    const sync = runSync();
+    return NextResponse.json({ status: 'ok', modelId, enabled, provider: models[idx].provider, sync });
   } catch (e: unknown) {
     return NextResponse.json({ status: 'error', error: e instanceof Error ? e.message : String(e) }, { status: 500 });
   }

package/app/api/gateway/sync.ts

@@ -2,16 +2,22 @@
  * Agent Gateway Sync
  *
  * Syncs the models.providers.rev4a config block to all agent containers
- * (or a single container) without touching model references (primary/fallback).
+ * without touching model references (primary/fallback).
  *
  * Import and call:
  *   syncAllAgents()          — sync all containers with AGENT_ID label
- *   syncAgent('container')   — sync a single container
+ *
+ * A single-container `syncAgent()` used to be exported too. Nothing called it —
+ * the create route builds the block with `buildRev4aProviderConfig()` and writes
+ * it with `openclaw config patch` itself — so it was removed.
  */
-import { execSync } from 'child_process';
+import { execSync, execFileSync } from 'child_process';
 import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { readProviderKeys } from './provider/keys';
-import { loadModelsConfig, type ModelConfigEntry } from '@/lib/model-catalogue';
+import { bundledCatalogueStatus, loadOfferedModels, type ModelConfigEntry } from '@/lib/model-catalogue';
+import { singleFileFromTar } from '@/lib/container-file';
 import { detectProviderGatewayUrl } from '@/lib/docker-utils';
 
 const PROVIDER_GATEWAY_BASE_URL = detectProviderGatewayUrl();
@@ -33,11 +39,8 @@ function modalityToInput(modality: string): string[] {
   return left.split('+').map((s) => s.trim()).filter((s) => ALLOWED_INPUT.has(s));
 }
 
-function getActiveRev4aModels(models: ModelConfigEntry[]): { id: string; name: string; input?: string[] }[] {
-  const providerKeys = readProviderKeys();
-  const configuredProviders = Object.keys(providerKeys);
-  return models
-    .filter((m) => m.enabled && configuredProviders.includes(m.provider))
+function getActiveRev4aModels(): { id: string; name: string; input?: string[] }[] {
+  return loadOfferedModels()
     .map((m) => {
       const entry: { id: string; name: string; input?: string[] } = { id: m.id, name: m.name };
       if (m.modality) entry.input = modalityToInput(m.modality);
@@ -45,54 +48,146 @@ function getActiveRev4aModels(models: ModelConfigEntry[]): { id: string; name: s
     });
 }
 
-function getAgentContainers(): string[] {
+/** A readable cause from a failed child process: its stderr if any, else the message. */
+function firstLine(e: unknown): string {
+  const err = e as { stderr?: string | Buffer; message?: string };
+  const text = (err.stderr ? err.stderr.toString() : '') || err.message || 'unknown error';
+  return text.trim().split('\n')[0];
+}
+
+/** A container carrying an AGENT_ID label, and whether it is running. */
+interface AgentContainer { name: string; running: boolean }
+
+/**
+ * Every container carrying an AGENT_ID label, running or stopped.
+ *
+ * Throws when Docker cannot be asked. It used to catch that and return `[]`,
+ * which made "the Docker daemon is not running" indistinguishable from "there are
+ * no agents": a model toggle made while Docker was stopped synced to nobody and
+ * still reported success. An empty list now means only the second.
+ *
+ * Stopped agents are included on purpose. This used to run `docker ps` without
+ * `-a`, so a catalogue change made while an agent was stopped skipped it, and
+ * starting it later brought back the old catalogue until someone ran Sync All.
+ */
+function getAgentContainers(): AgentContainer[] {
+  let raw: string;
   try {
-    const raw = execSync(
-      `docker ps --filter "label=AGENT_ID" --format '{{.Names}}'`,
-      { timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8' },
+    raw = execSync(
+      `docker ps -a --filter "label=AGENT_ID" --format '{{.Names}}\t{{.State}}'`,
+      { timeout: 5000, maxBuffer: 64 * 1024, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] },
     ).trim();
-    if (!raw) return [];
-    return raw.split('\n');
-  } catch {
-    return [];
+  } catch (e) {
+    throw new Error(firstLine(e));
+  }
+  if (!raw) return [];
+  return raw.split('\n')
+    .map((line) => {
+      const [name, state] = line.split('\t');
+      return { name: (name ?? '').trim(), running: (state ?? '').trim() === 'running' };
+    })
+    .filter((c) => c.name);
+}
+
+/**
+ * Why Docker cannot be asked right now, or undefined when it can.
+ *
+ * For callers that must decide *before* committing a change whether its sync can
+ * happen at all. A model toggle made while Docker was unreachable used to be saved
+ * and then reach no container, leaving the Gateway's checkboxes out of step with
+ * what the agents hold; checking first lets it be refused cleanly instead.
+ */
+export function dockerUnreachableReason(): string | undefined {
+  try {
+    getAgentContainers();
+    return undefined;
+  } catch (e) {
+    return (e as Error).message;
   }
 }
 
-function readContainerJson(container: string, remotePath: string): Record<string, unknown> {
+
+/**
+ * Read and parse a container's JSON config, running or stopped.
+ *
+ * Throws on any failure. It used to return `{}`, and the caller wrote that back
+ * with only the provider block added — so a single timed-out read replaced an
+ * agent's whole config (agents, gateway, channels) with `{ models: { providers:
+ * { rev4a } } }`. An empty object is refused for the same reason. Also returns
+ * the file mode, so a stopped container's file is written back unchanged in that
+ * respect.
+ */
+function readContainerJson(container: AgentContainer, remotePath: string): { config: Record<string, unknown>; mode: number } {
+  let raw: string;
+  let mode = 0o600;
+  if (container.running) {
+    raw = execFileSync('docker', ['exec', container.name, 'cat', remotePath], {
+      timeout: 8000, maxBuffer: 512 * 1024, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } else {
+    const file = singleFileFromTar(execFileSync('docker', ['cp', `${container.name}:${remotePath}`, '-'], {
+      timeout: 8000, maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+    }));
+    raw = file.body.toString('utf-8');
+    mode = file.mode;
+  }
+  let parsed: unknown;
   try {
-    const raw = execSync(
-      `docker exec ${container} cat ${remotePath}`,
-      { timeout: 8000, maxBuffer: 512 * 1024, encoding: 'utf-8' },
-    );
-    return JSON.parse(raw);
+    parsed = JSON.parse(raw);
   } catch {
-    return {};
+    // Not the parser's message: V8 quotes a slice of the input, this file holds
+    // tokens, and the error ends up in the sync summary shown in the browser.
+    throw new Error(`${remotePath} is not valid JSON; refusing to overwrite it`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || Object.keys(parsed).length === 0) {
+    throw new Error(`${remotePath} is empty or not a JSON object; refusing to overwrite it`);
   }
+  return { config: parsed as Record<string, unknown>, mode };
 }
 
-function writeContainerJson(container: string, remotePath: string, data: Record<string, unknown>): void {
+/**
+ * Write a container's JSON config, running or stopped.
+ *
+ * Running: through `docker exec`, truncating the file in place so its mode and
+ * owner stay as they are, and OpenClaw hot-applies the change. Stopped: through
+ * `docker cp`, the only way to reach it; the file is staged on the host with the
+ * original mode, lands on the agent's volume, and is read at next start.
+ */
+function writeContainerJson(container: AgentContainer, remotePath: string, data: Record<string, unknown>, mode: number): void {
   const jsonStr = JSON.stringify(data, null, 2);
-  // Use shell-quoted heredoc to avoid word-splitting on paths with spaces
-  execSync(
-    `docker exec -i ${container} sh -c "cat > '${remotePath}'"`,
-    { timeout: 10000, maxBuffer: 1024 * 1024, input: jsonStr },
-  );
+  if (container.running) {
+    execFileSync('docker', ['exec', '-i', container.name, 'sh', '-c', 'cat > "$1"', 'sh', remotePath], {
+      timeout: 10000, maxBuffer: 1024 * 1024, input: jsonStr, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return;
+  }
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rev4a-sync-'));
+  const staged = path.join(dir, path.basename(remotePath));
+  try {
+    fs.writeFileSync(staged, jsonStr);
+    fs.chmodSync(staged, mode);
+    execFileSync('docker', ['cp', staged, `${container.name}:${remotePath}`], {
+      timeout: 10000, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
 }
 
+
 /* ------------------------------------------------------------------ */
 /*  Sync functions                                                     */
 /* ------------------------------------------------------------------ */
 
 /**
  * Build the models.providers.rev4a config object from local state.
- * Shared between the create wizard and syncAgent — single source of truth
+ * Shared between the create route and syncAllAgents — single source of truth
  * for the provider block injected into every agent container.
  */
 export function buildRev4aProviderConfig(): { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string; input?: string[] }[] } {
   const providerKeys = readProviderKeys();
   const rev4aApiKey = providerKeys['rev4a'] || '';
-  const allModels = loadModelsConfig();
-  const activeModels = getActiveRev4aModels(allModels);
+  const activeModels = getActiveRev4aModels();
   return {
     baseUrl: PROVIDER_GATEWAY_BASE_URL,
     apiKey: rev4aApiKey,
@@ -102,65 +197,146 @@ export function buildRev4aProviderConfig(): { baseUrl: string; apiKey: string; a
 }
 
 /**
- * Sync models.providers.rev4a to all agent containers.
- * Does NOT touch agents.defaults.model or agents.list[].model.
+ * Write `models.providers.rev4a` into one running container.
+ *
+ * Throws instead of writing when the catalogue could not be read: an unreadable
+ * catalogue is not an empty one, and patching it in would strip every model from
+ * the agent. `syncAllAgents()` refuses for the same reason.
+ *
+ * No gateway restart: `config patch` reports "Change will apply without restarting
+ * the gateway" for a models-only patch, and the Gateway watches openclaw.json with
+ * gateway.reload defaulting to hybrid.
+ */
+export function patchRev4aProvider(container: string): void {
+  if (bundledCatalogueStatus() === 'unavailable') {
+    throw new Error('models.config.json could not be read; models.providers.rev4a left unchanged');
+  }
+  const input = JSON.stringify({ models: { providers: { rev4a: buildRev4aProviderConfig() } } });
+  execFileSync('docker', ['exec', '-i', container, 'sh', '-c', 'openclaw config patch --stdin'], {
+    timeout: 15000,
+    stdio: 'pipe',
+    input,
+  });
+}
+
+/** What a sync did, container by container. */
+export interface SyncOutcome {
+  /**
+   * True only when every agent container received the catalogue. Zero agents is
+   * ok — there is nothing to sync, which is the normal state on first run.
+   */
+  ok: boolean;
+  /** Models written into each container. */
+  activeModels: number;
+  /** Agent containers found. */
+  total: number;
+  synced: string[];
+  /** Of `synced`, the ones not running (stopped, paused, created): written with `docker cp`. Applied when started, or resumed. */
+  stopped: string[];
+  failed: { container: string; error: string }[];
+  /** Docker could not list containers at all, so nothing was attempted. */
+  dockerError?: string;
+  /** The catalogue block could not be built, so nothing was attempted. */
+  configError?: string;
+  /** One line for a person. Built here so every caller says the same thing. */
+  summary: string;
+}
+
+/** ", 2 of them not running" — those apply the change later, which is worth saying. */
+function stoppedNote(outcome: SyncOutcome): string {
+  return outcome.stopped.length ? `, ${outcome.stopped.length} of them not running` : '';
+}
+
+/**
+ * Push the offered catalogue into every agent container, and say exactly what
+ * happened.
+ *
+ * Returns an outcome instead of throwing: callers run this *after* committing a
+ * change — a key saved, a model toggled — and a failed propagation must not be
+ * reported as a failed save, because the save stands. The old signature returned
+ * loose strings that no caller inspected, so a sync that reached no container
+ * surfaced as success.
  */
-export function syncAllAgents(): string[] {
+export function syncAllAgents(): SyncOutcome {
   const rev4aProviderConfig = buildRev4aProviderConfig();
+  const outcome: SyncOutcome = {
+    ok: false,
+    activeModels: rev4aProviderConfig.models.length,
+    total: 0,
+    synced: [],
+    stopped: [],
+    failed: [],
+    summary: '',
+  };
+
   if (!rev4aProviderConfig.apiKey) {
-    return ['ERROR: REV4A_API_KEY not found in provider-keys.json (add "rev4a" key)'];
+    outcome.configError = 'REV4A_API_KEY not found in provider-keys.json (add "rev4a" key)';
+    outcome.summary = `Not applied to any agent: ${outcome.configError}.`;
+    return outcome;
   }
 
-  const containers = getAgentContainers();
-  const results: string[] = [`Active models: ${rev4aProviderConfig.models.length} across ${containers.length} agent(s)`];
+  // A catalogue that could not be read is not an empty catalogue: pushing it would
+  // strip every model from every agent.
+  if (bundledCatalogueStatus() === 'unavailable') {
+    outcome.configError = 'models.config.json could not be read, so there is no catalogue to push';
+    outcome.summary = `Not applied to any agent: ${outcome.configError}.`;
+    return outcome;
+  }
 
+  let containers: AgentContainer[];
+  try {
+    containers = getAgentContainers();
+  } catch (e) {
+    outcome.dockerError = (e as Error).message;
+    outcome.summary = `Not applied to any agent: Docker is unreachable (${outcome.dockerError}).`;
+    return outcome;
+  }
+
+  outcome.total = containers.length;
   for (const container of containers) {
     try {
-      const result = syncContainer(container, rev4aProviderConfig);
-      results.push(result);
+      syncContainer(container, rev4aProviderConfig);
+      outcome.synced.push(container.name);
+      if (!container.running) outcome.stopped.push(container.name);
     } catch (e: unknown) {
-      const err = e as { stderr?: string; message?: string };
-      results.push(`${container}: ERROR ${err.stderr || err.message || 'unknown'}`);
+      outcome.failed.push({ container: container.name, error: firstLine(e) });
     }
   }
 
-  if (containers.length === 0) {
-    results.push('No agent containers found');
+  outcome.ok = outcome.failed.length === 0;
+  if (outcome.total === 0) {
+    outcome.summary = 'No agent containers to sync.';
+  } else if (outcome.ok) {
+    outcome.summary = `Synced ${outcome.synced.length} of ${outcome.total} agent(s)${stoppedNote(outcome)}.`;
+  } else {
+    const names = outcome.failed.map((f) => `${f.container} (${f.error})`).join(', ');
+    outcome.summary = `Synced ${outcome.synced.length} of ${outcome.total} agent(s)${stoppedNote(outcome)}. Not applied to: ${names}.`;
   }
-
-  return results;
+  return outcome;
 }
 
 /**
- * Sync models.providers.rev4a to a single agent container.
- * Does NOT touch agents.defaults.model or agents.list[].model.
- */
-export function syncAgent(containerName: string): string {
-  const rev4aProviderConfig = buildRev4aProviderConfig();
-  if (!rev4aProviderConfig.apiKey) {
-    throw new Error('REV4A_API_KEY not found in provider-keys.json (add "rev4a" key)');
-  }
-  return syncContainer(containerName, rev4aProviderConfig);
-}
-
-/**
- * Internal: write models.providers.rev4a to one container and restart its gateway.
+ * Internal: write models.providers.rev4a into one container's openclaw.json.
  */
 function syncContainer(
-  container: string,
+  container: AgentContainer,
   rev4aProviderConfig: { baseUrl: string; apiKey: string; api: string; models: { id: string; name: string }[] },
 ): string {
   const remotePath = '/root/.openclaw/openclaw.json';
-  const config = readContainerJson(container, remotePath) as Record<string, unknown>;
+  // Read first. If this throws, the container is reported as failed and nothing
+  // below runs — in particular nothing is written.
+  const { config, mode } = readContainerJson(container, remotePath);
 
-  // Clean up stale files from old versions
-  try {
-    execSync(
-      `docker exec ${container} sh -c 'rm -f /root/.openclaw/agents/main/agent/models.json /root/.openclaw/agents/main/agent/auth-profiles.json'`,
-      { timeout: 5000 },
-    );
-  } catch {
-    // non-fatal
+  // Clean up stale files from old versions. Needs exec, so running containers
+  // only; a stopped one is cleaned on the first sync after it starts.
+  if (container.running) {
+    try {
+      execFileSync('docker', ['exec', container.name, 'rm', '-f',
+        '/root/.openclaw/agents/main/agent/models.json',
+        '/root/.openclaw/agents/main/agent/auth-profiles.json'], { timeout: 5000, stdio: 'ignore' });
+    } catch {
+      // non-fatal
+    }
   }
 
   // Write/overwrite models.providers.rev4a — do NOT touch agents.*
@@ -169,7 +345,7 @@ function syncContainer(
   (models.providers as Record<string, unknown>)['rev4a'] = rev4aProviderConfig;
   config.models = models;
 
-  writeContainerJson(container, remotePath, config);
+  writeContainerJson(container, remotePath, config, mode);
 
   // No gateway restart: this only writes models.providers.rev4a, and the Gateway
   // watches openclaw.json and hot-applies it. OpenClaw's own config tooling says
@@ -182,5 +358,5 @@ function syncContainer(
   // The restart used to cost ~7.5s per container, serially — roughly 52s of
   // fully blocked event loop on a seven-agent host, every time a provider key or
   // model toggle was saved, to do something the Gateway had already done.
-  return `${container}: synced`;
+  return `${container.name}: synced`;
 }