diff --git a/docs-site/src/content/docs/reference/management-api.md b/docs-site/src/content/docs/reference/management-api.md
index 0a1b76c94e4..620aca41217 100644
--- a/docs-site/src/content/docs/reference/management-api.md
+++ b/docs-site/src/content/docs/reference/management-api.md
@@ -482,6 +482,30 @@ can still fail when a recorded session has no surviving rollout file.
 | `PUT, DELETE /api/custom-models/{id}` | Edit or delete one custom model | 400 invalid id/fields; 404 not found; 409 duplicate model |
 | `GET, PUT /api/selected-models` | Read provider allowlists and availability, or replace one allowlist | 400 missing provider/body; 404 unknown provider; PUT 409 `initial_model_selection_pending` |
 | `GET, PUT /api/model-presets` | Read preset summaries or choose preset/all/custom mode | 400 invalid mode or unsupported preset; 404 unknown provider; PUT 409 `initial_model_selection_pending` |
+| `PUT /api/model-settings` | Edit one routed model's capability axes in place | 400 missing provider/modelId, unknown or native/combo provider, malformed field, or an invalid default effort for the resulting ladder |
+
+`PUT /api/model-settings` takes `{ provider, modelId }` plus any of `contextWindow`,
+`inputModalities`, `reasoningEfforts`, and `defaultReasoningEffort`. It writes the
+provider-level per-model maps the runtime already reads (`modelContextWindows`,
+`modelCapabilities.<modelId>.inputModalities`, `modelReasoningEfforts`,
+`modelDefaultReasoningEfforts`), so an edited row keeps its discovery provenance instead of
+being replaced by a custom model. `inputModalities` accepts `text`, `image`, and `audio`;
+`reasoningEfforts` must be a subset of the efforts the runtime knows.
+
+Every field is optional, and `null` **clears** the declaration rather than writing a default,
+which hands the fact back to the registry, the catalog, and the provider. An empty
+`inputModalities` array also clears, while an empty `reasoningEfforts` array is stored as an
+explicit "this model has no reasoning rungs" override — it does not clear.
+An emptied per-model map is removed instead of left as `{}`. A request that changes nothing
+answers `changed: false` with the stored state, which is how an editor distinguishes "no
+override to restore" from "restored one". A request that does change something persists the
+config, drops that provider's cached `/models` result, and reports `catalogRefresh` — the gather
+bakes resolved hints into the rows it caches, and a cache hit may only lower a configured window,
+so a raised or cleared override would otherwise read back the previous answer for the whole TTL.
+Only routed providers are addressable: `openai` is the
+native passthrough lane and `combo` is a synthetic row, so neither is a provider whose per-model
+maps these facts come from. Display name is not part of this route; use
+`PUT /api/providers/{provider}/model-display-names`.
 
 A manual model replaces the Models dashboard row with the same provider and model ID.
 For OpenAI, the manual row keeps `openai/<model>` and supports the same visibility controls
diff --git a/gui/src/components/ModelSettingsDialog.tsx b/gui/src/components/ModelSettingsDialog.tsx
new file mode 100644
index 00000000000..46e80007f80
--- /dev/null
+++ b/gui/src/components/ModelSettingsDialog.tsx
@@ -0,0 +1,395 @@
+import { useEffect, useId, useRef, useState } from "react";
+import { confirmAction } from "../action-dialogs";
+import { createBoundedFetch, type BoundedFetch } from "../bounded-fetch";
+import { readJsonOrThrow } from "../fetch-json";
+import { useT, type TKey } from "../i18n/shared";
+import { Notice, Select } from "../ui";
+import { CUSTOM_OPTION, REASONING_EFFORT_LEVELS, type ModelRow } from "../pages/models-shared";
+
+/**
+ * The per-model overrides on ONE routed row, in the shape the row already reports them.
+ *
+ * Three axes, and no fourth. Display name is absent on purpose: the row has its own editor for
+ * it, with its own provenance display, and a second control writing the same key is two
+ * statements that can drift apart. This dialog owns what nothing else edits — the context
+ * window, the modality declaration, and the reasoning ladder — so "restore" means "clear the
+ * capability overrides", which is a promise it can keep.
+ *
+ * Every field is optional and clearing one is a distinct intent from writing a value: an empty
+ * window sends `null`, which hands the fact back to the registry, the catalog and the provider
+ * default instead of pinning today's answer as an override that outlives its source.
+ */
+
+/** The modalities the API accepts. `video` is absent: the wire carries text and image parts. */
+const MODALITIES = ["text", "image", "audio"] as const;
+
+const CONTEXT_PRESETS = ["100000", "128000", "200000", "256000", "352000", "500000", "1000000"];
+
+const REQUEST_TIMEOUT_MS = 60_000;
+
+type Phase = "ready" | "saving" | "restoring" | "unknown";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** What the row reported when the dialog opened: the form's start, and the save diff's baseline. */
+interface SettingsBaseline {
+  contextWindow: string;
+  modalities: string[];
+  reasoning: boolean;
+  ladder: string[];
+  defaultEffort: string;
+}
+
+function baselineOf(row: ModelRow): SettingsBaseline {
+  const reasoning = row.reasoningOverridden === true;
+  return {
+    contextWindow: row.contextWindow ? String(row.contextWindow) : "",
+    // The DECLARATION, never the row's own `inputModalities`. That one is the catalog value:
+    // pre-filling from it made an undeclared model look declared, and because an untouched field
+    // is not submitted, every save came back as "nothing changed" and the row never moved.
+    modalities: Array.isArray(row.inputModalitiesDeclared) ? [...row.inputModalitiesDeclared] : [],
+    reasoning,
+    // The ladder only counts as the operator's when the config really overrides it: OpenCodex
+    // writes the registry ladder into the config itself, so key presence would tick this box on
+    // every model that merely inherits its levels.
+    ladder: reasoning && Array.isArray(row.reasoningEfforts) ? [...row.reasoningEfforts] : [],
+    defaultEffort: reasoning ? (row.defaultReasoningEffort ?? "") : "",
+  };
+}
+
+function sortedKey(values: readonly string[]): string {
+  return [...values].sort().join(",");
+}
+
+/** undefined when the draft is not a usable window, null when the operator cleared it. */
+function parseContextWindow(raw: string): number | null | undefined {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  const value = Number(trimmed.replace(/[_,\s]/g, ""));
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+interface ModelSettingsDialogProps {
+  row: ModelRow;
+  apiBase: string;
+  /** Reload the catalog. Resolves false when the reload failed, so the dialog can say so. */
+  onRefresh: (signal: AbortSignal) => Promise<boolean>;
+  onFeedback: (ok: boolean, message: string) => void;
+  onClose: () => void;
+}
+
+export default function ModelSettingsDialog({ row, apiBase, onRefresh, onFeedback, onClose }: ModelSettingsDialogProps) {
+  const t = useT();
+  const id = useId();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const submitRef = useRef<HTMLButtonElement>(null);
+  const requestRef = useRef<BoundedFetch | null>(null);
+  // State rather than a ref: the form's start values are read during render to seed the fields,
+  // and a ref read in render is exactly what the React Compiler lint refuses.
+  const [baseline] = useState<SettingsBaseline>(() => baselineOf(row));
+  const [phase, setPhase] = useState<Phase>("ready");
+  const [contextDraft, setContextDraft] = useState(() => baseline.contextWindow);
+  const [customContext, setCustomContext] = useState(() => (
+    baseline.contextWindow !== "" && !CONTEXT_PRESETS.includes(baseline.contextWindow)
+  ));
+  const [modalities, setModalities] = useState<string[]>(() => [...baseline.modalities]);
+  const [reasoning, setReasoning] = useState(() => baseline.reasoning);
+  const [ladder, setLadder] = useState<string[]>(() => [...baseline.ladder]);
+  const [defaultEffort, setDefaultEffort] = useState(() => baseline.defaultEffort);
+  const [errorKey, setErrorKey] = useState<TKey | null>(null);
+  const busy = phase !== "ready";
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog && !dialog.open) dialog.showModal();
+    return () => { if (dialog?.open) dialog.close(); };
+  }, []);
+
+  useEffect(() => {
+    if (phase === "unknown") submitRef.current?.focus();
+  }, [phase]);
+
+  const toggleReasoning = (next: boolean) => {
+    setReasoning(next);
+    if (!next) return;
+    // First enable seeds from what the model advertises rather than the full shared ladder: a
+    // provider that accepts only a subset would otherwise be handed levels its API rejects.
+    if (ladder.length > 0) return;
+    const advertised = Array.isArray(row.reasoningEfforts) ? row.reasoningEfforts : undefined;
+    setLadder(advertised && advertised.length > 0 ? [...advertised] : [...REASONING_EFFORT_LEVELS]);
+  };
+
+  const toggleLevel = (level: string, on: boolean) => {
+    setLadder(prev => (on ? [...prev, level] : prev.filter(value => value !== level)));
+    // The default has to stay inside the ladder, so dropping its level drops it too.
+    if (!on && defaultEffort === level) setDefaultEffort("");
+  };
+
+  const requestClose = () => {
+    if (!busy) onClose();
+  };
+
+  const send = async (patch: Record<string, unknown>, restoring: boolean) => {
+    const bounded = createBoundedFetch(REQUEST_TIMEOUT_MS);
+    requestRef.current = bounded;
+    setPhase(restoring ? "restoring" : "saving");
+    setErrorKey(null);
+    let confirmed = false;
+    try {
+      const response = await fetch(apiBase + "/api/model-settings", {
+        method: "PUT",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ provider: row.provider, modelId: row.id, ...patch }),
+        signal: bounded.signal,
+      });
+      const result = await readJsonOrThrow<unknown>(response);
+      bounded.signal.throwIfAborted();
+      // Validate the receipt against the request: a 200 for another row would otherwise be
+      // reported as this row's save, and the reload would appear to disagree with the toast.
+      if (!isRecord(result) || result.ok !== true || result.provider !== row.provider || result.modelId !== row.id) {
+        throw new Error("invalid model-settings receipt");
+      }
+      if (requestRef.current !== bounded) return;
+      confirmed = true;
+      const changed = result.changed === false;
+      if (!await onRefresh(bounded.signal)) throw new Error("catalog refresh failed");
+      bounded.signal.throwIfAborted();
+      if (requestRef.current !== bounded) return;
+      if (restoring) {
+        onFeedback(true, t(changed ? "models.settingsNothingToRestore" : "models.settingsRestored", { model: row.namespaced }));
+      } else {
+        onFeedback(true, t("models.settingsSaved", { model: row.namespaced }));
+      }
+      onClose();
+    } catch {
+      if (requestRef.current !== bounded) return;
+      setPhase("unknown");
+      setErrorKey(confirmed ? "models.settingsRefreshFailed" : "models.settingsSaveFailed");
+    } finally {
+      bounded.clear();
+      if (requestRef.current === bounded) requestRef.current = null;
+    }
+  };
+
+  const submit = () => {
+    if (busy) return;
+    const parsedWindow = parseContextWindow(contextDraft);
+    if (parsedWindow === undefined) { setErrorKey("models.contextInvalid"); return; }
+    const base = baseline;
+    const patch: Record<string, unknown> = {};
+    if (contextDraft.trim() !== base.contextWindow) patch.contextWindow = parsedWindow;
+    if (sortedKey(modalities) !== sortedKey(base.modalities)) {
+      patch.inputModalities = modalities.length > 0 ? [...modalities] : null;
+    }
+    const ladderKey = reasoning ? sortedKey(ladder) : "";
+    if (reasoning !== base.reasoning || ladderKey !== sortedKey(base.ladder)) {
+      patch.reasoningEfforts = reasoning ? [...ladder] : null;
+    }
+    const nextDefault = reasoning && ladder.includes(defaultEffort) ? defaultEffort : "";
+    if (nextDefault !== base.defaultEffort) patch.defaultReasoningEffort = nextDefault || null;
+    // Only what the operator actually touched is submitted. Writing an untouched field would
+    // convert a fact the row merely inherits into a stored override, which is the failure this
+    // whole surface exists to avoid.
+    if (Object.keys(patch).length === 0) { onClose(); return; }
+    void send(patch, false);
+  };
+
+  const restore = async () => {
+    if (busy) return;
+    const confirmed = await confirmAction({
+      message: t("models.settingsRestoreConfirm", { model: row.namespaced }),
+      confirmLabel: t("models.settingsRestore"),
+      tone: "danger",
+    });
+    if (!confirmed) return;
+    // Every axis at once, and it writes immediately rather than resetting the form: a form-level
+    // reset would still need a save, and that save would re-pin the values it had just restored.
+    void send({ contextWindow: null, inputModalities: null, reasoningEfforts: null, defaultReasoningEffort: null }, true);
+  };
+
+  const inheritedModalities = Array.isArray(row.inputModalities) ? row.inputModalities.join(", ") : "";
+
+  return (
+    <dialog
+      ref={dialogRef}
+      className="modal-overlay"
+      aria-labelledby={id + "-title"}
+      onCancel={event => { event.preventDefault(); requestClose(); }}
+    >
+      <button
+        type="button"
+        className="modal-backdrop-dismiss"
+        aria-label={t("common.close")}
+        tabIndex={-1}
+        disabled={busy}
+        onClick={requestClose}
+      />
+      {/*
+        `model-display-name-dialog` is reused rather than a new modifier: it is the shared narrow
+        dialog shell (460px, stacked actions on a small viewport), and gui/src/styles.css is at its
+        file-size cap, so a second class with the same rules could not be added.
+      */}
+      <form
+        className="modal-card model-display-name-dialog"
+        role="document"
+        noValidate
+        aria-busy={busy}
+        onClick={event => event.stopPropagation()}
+        onSubmit={event => { event.preventDefault(); submit(); }}
+      >
+        <div className="modal-head">
+          <h3 id={id + "-title"}>{t("models.settingsTitle", { model: row.namespaced })}</h3>
+          <button type="button" className="btn btn-ghost btn-sm" disabled={busy} onClick={requestClose}>
+            {t("common.close")}
+          </button>
+        </div>
+
+        {errorKey && <Notice tone="err">{t(errorKey)}</Notice>}
+
+        <div className="models-field-stack">
+          <div className="text-label models-field">
+            {t("models.customFieldModelId")}
+            <code className="mono text-control">{row.namespaced}</code>
+          </div>
+
+          <label className="text-label models-field">
+            {t("models.customFieldContext")}
+            <div className="row models-field-row">
+              <Select
+                value={customContext ? CUSTOM_OPTION : contextDraft}
+                options={[
+                  { value: "", label: "—" },
+                  { value: "100000", label: "100k" },
+                  { value: "128000", label: "128k" },
+                  { value: "200000", label: "200k" },
+                  { value: "256000", label: "256k" },
+                  { value: "352000", label: "352k" },
+                  { value: "500000", label: "500k" },
+                  { value: "1000000", label: "1M" },
+                  { value: CUSTOM_OPTION, label: t("models.custom") },
+                ]}
+                onChange={value => {
+                  if (value === CUSTOM_OPTION) { setCustomContext(true); return; }
+                  setCustomContext(false);
+                  setContextDraft(value);
+                }}
+                disabled={busy}
+                label={t("models.customFieldContext")}
+              />
+              {customContext && (
+                <input
+                  className="input"
+                  style={{ width: 120 }}
+                  inputMode="numeric"
+                  value={contextDraft}
+                  onChange={event => setContextDraft(event.target.value)}
+                  disabled={busy}
+                  placeholder={t("models.customPlaceholder")}
+                  aria-label={t("models.customFieldContext")}
+                />
+              )}
+            </div>
+          </label>
+
+          <div className="text-label models-field">
+            {t("models.customFieldModalities")}
+            <div className="row models-field-row">
+              {MODALITIES.map(modality => (
+                <label key={modality} className="row models-modality-option">
+                  <input
+                    type="checkbox"
+                    checked={modalities.includes(modality)}
+                    onChange={event => {
+                      setModalities(prev => (
+                        event.target.checked ? [...prev, modality] : prev.filter(value => value !== modality)
+                      ));
+                    }}
+                    disabled={busy}
+                  />
+                  <span className="text-control">{modality}</span>
+                </label>
+              ))}
+            </div>
+            {modalities.length === 0 && (
+              // No box ticked is a real state — undeclared — not an empty model. Say what is
+              // being followed instead, or the blank row reads as "this model accepts nothing".
+              <span className="muted text-caption">
+                {t("models.settingsModalitiesInherit", {
+                  modalities: inheritedModalities || t("models.settingsModalitiesUnknown"),
+                })}
+              </span>
+            )}
+          </div>
+
+          <div className="text-label models-field">
+            {t("models.customFieldReasoning")}
+            <div className="row models-field-row">
+              <label className="row models-modality-option">
+                <input
+                  type="checkbox"
+                  checked={reasoning}
+                  onChange={event => toggleReasoning(event.target.checked)}
+                  disabled={busy}
+                />
+                <span className="text-control">{t("models.customFieldReasoningOverride")}</span>
+              </label>
+            </div>
+            {reasoning && (
+              <div className="row models-field-row" style={{ flexWrap: "wrap" }}>
+                {REASONING_EFFORT_LEVELS.map(level => (
+                  <label key={level} className="row models-modality-option">
+                    <input
+                      type="checkbox"
+                      checked={ladder.includes(level)}
+                      onChange={event => toggleLevel(level, event.target.checked)}
+                      disabled={busy}
+                    />
+                    <span className="text-control">{t(("models.reasoningEffort." + level) as TKey)}</span>
+                  </label>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {reasoning && (
+            <label className="text-label models-field">
+              {t("models.settingsDefaultEffort")}
+              <div className="row models-field-row">
+                <Select
+                  value={defaultEffort}
+                  options={[
+                    { value: "", label: "—" },
+                    ...ladder.map(level => ({ value: level, label: t(("models.reasoningEffort." + level) as TKey) })),
+                  ]}
+                  onChange={setDefaultEffort}
+                  disabled={busy}
+                  label={t("models.settingsDefaultEffort")}
+                />
+              </div>
+            </label>
+          )}
+        </div>
+
+        <div className="modal-actions">
+          <button
+            type="button"
+            className="btn btn-ghost"
+            title={t("models.settingsRestoreHint")}
+            disabled={busy}
+            onClick={() => void restore()}
+          >
+            {t("models.settingsRestore")}
+          </button>
+          <button type="button" className="btn btn-ghost" onClick={requestClose} disabled={busy}>
+            {t("common.cancel")}
+          </button>
+          <button ref={submitRef} type="submit" className="btn btn-primary" disabled={busy}>
+            {busy ? t("models.customSaving") : t("models.customApply")}
+          </button>
+        </div>
+      </form>
+    </dialog>
+  );
+}
diff --git a/gui/src/i18n/de.ts b/gui/src/i18n/de.ts
index 2b83d98306a..7bf30d182f4 100644
--- a/gui/src/i18n/de.ts
+++ b/gui/src/i18n/de.ts
@@ -723,6 +723,18 @@ export const de: Record<TKey, string> = {
   "models.customAdd": "Benutzerdefiniertes Modell hinzufügen",
   "models.customAddTitle": "Benutzerdefiniertes Modell hinzufügen — {provider}",
   "models.customEditTitle": "Benutzerdefiniertes Modell bearbeiten — {provider}",
+  "models.settingsTitle": "Modell bearbeiten — {model}",
+  "models.settingsSaved": "Modelleinstellungen für {model} gespeichert",
+  "models.settingsSaveFailed": "Die Modelleinstellungen konnten nicht gespeichert werden.",
+  "models.settingsRefreshFailed": "Gespeichert, aber die Modellliste wurde nicht neu geladen. Öffne die Zeile erneut, um die gespeicherten Werte zu sehen.",
+  "models.settingsDefaultEffort": "Standardstufe",
+  "models.settingsModalitiesInherit": "Nicht überschrieben — folgt derzeit der Upstream-Deklaration: {modalities}",
+  "models.settingsModalitiesUnknown": "nicht deklariert",
+  "models.settingsRestore": "Zurücksetzen",
+  "models.settingsRestoreHint": "Alle Überschreibungen dieses Modells entfernen und wieder die berechneten Werte verwenden.",
+  "models.settingsRestoreConfirm": "{model} auf die berechneten Werte zurücksetzen? Damit werden Kontextfenster, Modalität und Reasoning-Überschreibungen entfernt.",
+  "models.settingsRestored": "{model} auf die berechneten Werte zurückgesetzt",
+  "models.settingsNothingToRestore": "{model} hat keine Überschreibungen — entspricht bereits den berechneten Werten",
   "models.customAdded": "Benutzerdefiniertes Modell hinzugefügt",
   "models.customUpdated": "Benutzerdefiniertes Modell aktualisiert",
   "models.customDeleted": "Benutzerdefiniertes Modell gelöscht",
diff --git a/gui/src/i18n/en.ts b/gui/src/i18n/en.ts
index dad65cfc6dd..4fc43d7de6f 100644
--- a/gui/src/i18n/en.ts
+++ b/gui/src/i18n/en.ts
@@ -752,6 +752,18 @@ export const en = {
   "models.customAdd": "Add custom model",
   "models.customAddTitle": "Add custom model — {provider}",
   "models.customEditTitle": "Edit custom model — {provider}",
+  "models.settingsTitle": "Edit model — {model}",
+  "models.settingsSaved": "Model settings saved for {model}",
+  "models.settingsSaveFailed": "Could not save the model settings.",
+  "models.settingsRefreshFailed": "Saved, but the model list did not reload. Reopen the row to see the stored values.",
+  "models.settingsDefaultEffort": "Default level",
+  "models.settingsModalitiesInherit": "Not overridden — currently following the upstream declaration: {modalities}",
+  "models.settingsModalitiesUnknown": "not declared",
+  "models.settingsRestore": "Restore",
+  "models.settingsRestoreHint": "Clear every override on this model and fall back to the computed values.",
+  "models.settingsRestoreConfirm": "Restore {model} to the computed values? This clears its context window, modality and reasoning overrides.",
+  "models.settingsRestored": "{model} restored to the computed values",
+  "models.settingsNothingToRestore": "{model} carries no overrides; already the computed values",
   "pws.manageModelVisibility": "Manage visibility in Models",
   "pws.modelOwnershipLoading": "Checking model definitions…",
   "pws.modelOwnershipFailed": "Model definitions could not be loaded. Retry before making changes.",
diff --git a/gui/src/i18n/fr.ts b/gui/src/i18n/fr.ts
index ce302bb3e37..0947bd18eb5 100644
--- a/gui/src/i18n/fr.ts
+++ b/gui/src/i18n/fr.ts
@@ -737,6 +737,18 @@ export const fr: Record<TKey, string> = {
   "models.customAdd": "Ajouter un modèle personnalisé",
   "models.customAddTitle": "Ajouter un modèle personnalisé — {provider}",
   "models.customEditTitle": "Modifier le modèle personnalisé — {provider}",
+  "models.settingsTitle": "Modifier le modèle — {model}",
+  "models.settingsSaved": "Paramètres du modèle enregistrés pour {model}",
+  "models.settingsSaveFailed": "Impossible d'enregistrer les paramètres du modèle.",
+  "models.settingsRefreshFailed": "Enregistré, mais la liste des modèles n'a pas été rechargée. Rouvrez la ligne pour voir les valeurs stockées.",
+  "models.settingsDefaultEffort": "Niveau par défaut",
+  "models.settingsModalitiesInherit": "Non remplacé — suit actuellement la déclaration amont : {modalities}",
+  "models.settingsModalitiesUnknown": "non déclaré",
+  "models.settingsRestore": "Réinitialiser",
+  "models.settingsRestoreHint": "Supprimer toutes les substitutions de ce modèle et revenir aux valeurs calculées.",
+  "models.settingsRestoreConfirm": "Réinitialiser {model} aux valeurs calculées ? Cela supprime ses substitutions de fenêtre de contexte, de modalité et de raisonnement.",
+  "models.settingsRestored": "{model} réinitialisé aux valeurs calculées",
+  "models.settingsNothingToRestore": "{model} n'a aucune substitution — déjà les valeurs calculées",
   "models.customAdded": "Modèle personnalisé ajouté",
   "models.customUpdated": "Modèle personnalisé mis à jour",
   "models.customDeleted": "Modèle personnalisé supprimé",
diff --git a/gui/src/i18n/ja.ts b/gui/src/i18n/ja.ts
index 938ee65ec43..5a3cba36ada 100644
--- a/gui/src/i18n/ja.ts
+++ b/gui/src/i18n/ja.ts
@@ -3018,6 +3018,18 @@ export const ja: Record<TKey, string> = {
   "models.customAdd": "Add custom model",
   "models.customAddTitle": "Add custom model — {provider}",
   "models.customEditTitle": "Edit custom model — {provider}",
+  "models.settingsTitle": "モデルを編集 — {model}",
+  "models.settingsSaved": "{model} のモデル設定を保存しました",
+  "models.settingsSaveFailed": "モデル設定を保存できませんでした。",
+  "models.settingsRefreshFailed": "保存しましたが、モデル一覧を再読み込みできませんでした。行を開き直して保存済みの値を確認してください。",
+  "models.settingsDefaultEffort": "既定レベル",
+  "models.settingsModalitiesInherit": "未上書き — 現在は上流の宣言に従います: {modalities}",
+  "models.settingsModalitiesUnknown": "未宣言",
+  "models.settingsRestore": "リセット",
+  "models.settingsRestoreHint": "このモデルの上書きをすべて削除し、計算値に戻します。",
+  "models.settingsRestoreConfirm": "{model} を計算値に戻しますか？コンテキストウィンドウ、モダリティ、推論の上書きが削除されます。",
+  "models.settingsRestored": "{model} を計算値に戻しました",
+  "models.settingsNothingToRestore": "{model} に上書きはありません — すでに計算値です",
   "models.customAdded": "Custom model added",
   "models.customUpdated": "Custom model updated",
   "models.customDeleted": "Custom model deleted",
diff --git a/gui/src/i18n/ko.ts b/gui/src/i18n/ko.ts
index 80b4af705c1..a00613531a9 100644
--- a/gui/src/i18n/ko.ts
+++ b/gui/src/i18n/ko.ts
@@ -734,6 +734,18 @@ export const ko: Record<TKey, string> = {
   "models.customAdd": "커스텀 모델 추가",
   "models.customAddTitle": "커스텀 모델 추가 — {provider}",
   "models.customEditTitle": "커스텀 모델 편집 — {provider}",
+  "models.settingsTitle": "모델 편집 — {model}",
+  "models.settingsSaved": "{model} 모델 설정을 저장했습니다",
+  "models.settingsSaveFailed": "모델 설정을 저장하지 못했습니다.",
+  "models.settingsRefreshFailed": "저장했지만 모델 목록을 다시 불러오지 못했습니다. 행을 다시 열어 저장된 값을 확인하세요.",
+  "models.settingsDefaultEffort": "기본 수준",
+  "models.settingsModalitiesInherit": "재정의되지 않음 — 현재 업스트림 선언을 따릅니다: {modalities}",
+  "models.settingsModalitiesUnknown": "선언되지 않음",
+  "models.settingsRestore": "초기화",
+  "models.settingsRestoreHint": "이 모델의 모든 재정의를 지우고 계산된 값으로 되돌립니다.",
+  "models.settingsRestoreConfirm": "{model}을(를) 계산된 값으로 초기화할까요? 컨텍스트 창, 모달리티, 추론 재정의가 삭제됩니다.",
+  "models.settingsRestored": "{model}을(를) 계산된 값으로 초기화했습니다",
+  "models.settingsNothingToRestore": "{model}에는 재정의가 없습니다 — 이미 계산된 값입니다",
   "models.customAdded": "커스텀 모델 추가됨",
   "models.customUpdated": "커스텀 모델 수정됨",
   "models.customDeleted": "커스텀 모델 삭제됨",
diff --git a/gui/src/i18n/ru.ts b/gui/src/i18n/ru.ts
index 2fcf9a11a33..453c0616fd3 100644
--- a/gui/src/i18n/ru.ts
+++ b/gui/src/i18n/ru.ts
@@ -736,6 +736,18 @@ export const ru: Record<TKey, string> = {
   "models.customAdd": "Добавить пользовательскую модель",
   "models.customAddTitle": "Добавить пользовательскую модель — {provider}",
   "models.customEditTitle": "Изменить пользовательскую модель — {provider}",
+  "models.settingsTitle": "Изменить модель — {model}",
+  "models.settingsSaved": "Настройки модели {model} сохранены",
+  "models.settingsSaveFailed": "Не удалось сохранить настройки модели.",
+  "models.settingsRefreshFailed": "Сохранено, но список моделей не перезагрузился. Откройте строку снова, чтобы увидеть сохранённые значения.",
+  "models.settingsDefaultEffort": "Уровень по умолчанию",
+  "models.settingsModalitiesInherit": "Не переопределено — сейчас используется объявление провайдера: {modalities}",
+  "models.settingsModalitiesUnknown": "не объявлено",
+  "models.settingsRestore": "Сбросить",
+  "models.settingsRestoreHint": "Удалить все переопределения этой модели и вернуться к вычисленным значениям.",
+  "models.settingsRestoreConfirm": "Сбросить {model} к вычисленным значениям? Это удалит переопределения окна контекста, модальности и рассуждений.",
+  "models.settingsRestored": "{model} сброшена к вычисленным значениям",
+  "models.settingsNothingToRestore": "У {model} нет переопределений — уже вычисленные значения",
   "models.customAdded": "Пользовательская модель добавлена",
   "models.customUpdated": "Пользовательская модель обновлена",
   "models.customDeleted": "Пользовательская модель удалена",
diff --git a/gui/src/i18n/tr.ts b/gui/src/i18n/tr.ts
index 4d7f56ccedd..6a7b7eb0d4b 100644
--- a/gui/src/i18n/tr.ts
+++ b/gui/src/i18n/tr.ts
@@ -739,6 +739,18 @@ export const tr: Record<TKey, string> = {
   "models.customAdd": "Özel model ekle",
   "models.customAddTitle": "Özel model ekle — {provider}",
   "models.customEditTitle": "Özel modeli düzenle — {provider}",
+  "models.settingsTitle": "Modeli düzenle — {model}",
+  "models.settingsSaved": "{model} için model ayarları kaydedildi",
+  "models.settingsSaveFailed": "Model ayarları kaydedilemedi.",
+  "models.settingsRefreshFailed": "Kaydedildi, ancak model listesi yenilenemedi. Saklanan değerleri görmek için satırı yeniden açın.",
+  "models.settingsDefaultEffort": "Varsayılan düzey",
+  "models.settingsModalitiesInherit": "Geçersiz kılınmadı — şu anda üst kaynak bildirimine uyuluyor: {modalities}",
+  "models.settingsModalitiesUnknown": "bildirilmemiş",
+  "models.settingsRestore": "Sıfırla",
+  "models.settingsRestoreHint": "Bu modeldeki tüm geçersiz kılmaları kaldır ve hesaplanan değerlere dön.",
+  "models.settingsRestoreConfirm": "{model} hesaplanan değerlere sıfırlansın mı? Bağlam penceresi, modalite ve akıl yürütme geçersiz kılmaları silinir.",
+  "models.settingsRestored": "{model} hesaplanan değerlere sıfırlandı",
+  "models.settingsNothingToRestore": "{model} için geçersiz kılma yok — zaten hesaplanan değerler",
   "models.customAdded": "Özel model eklendi",
   "models.customUpdated": "Özel model güncellendi",
   "models.customDeleted": "Özel model silindi",
diff --git a/gui/src/i18n/vi.ts b/gui/src/i18n/vi.ts
index 5dba045198c..13093dad90a 100644
--- a/gui/src/i18n/vi.ts
+++ b/gui/src/i18n/vi.ts
@@ -737,6 +737,18 @@ export const vi: Record<TKey, string> = {
   "models.customAdd": "Thêm model tuỳ chỉnh",
   "models.customAddTitle": "Thêm model tuỳ chỉnh — {provider}",
   "models.customEditTitle": "Chỉnh sửa model tuỳ chỉnh — {provider}",
+  "models.settingsTitle": "Chỉnh sửa model — {model}",
+  "models.settingsSaved": "Đã lưu cài đặt model cho {model}",
+  "models.settingsSaveFailed": "Không lưu được cài đặt model.",
+  "models.settingsRefreshFailed": "Đã lưu, nhưng danh sách model không tải lại được. Mở lại dòng để xem giá trị đã lưu.",
+  "models.settingsDefaultEffort": "Mức mặc định",
+  "models.settingsModalitiesInherit": "Chưa ghi đè — hiện theo khai báo từ nhà cung cấp: {modalities}",
+  "models.settingsModalitiesUnknown": "chưa khai báo",
+  "models.settingsRestore": "Khôi phục",
+  "models.settingsRestoreHint": "Xoá mọi ghi đè trên model này và quay về giá trị do chương trình tính.",
+  "models.settingsRestoreConfirm": "Khôi phục {model} về giá trị do chương trình tính? Thao tác này xoá ghi đè về cửa sổ ngữ cảnh, modality và suy luận.",
+  "models.settingsRestored": "Đã khôi phục {model} về giá trị do chương trình tính",
+  "models.settingsNothingToRestore": "{model} không có ghi đè — đã là giá trị do chương trình tính",
   "pws.manageModelVisibility": "Quản lý hiển thị trong Models",
   "pws.modelOwnershipLoading": "Đang kiểm tra định nghĩa model…",
   "pws.modelOwnershipFailed": "Không thể tải định nghĩa model. Hãy thử lại trước khi thay đổi.",
diff --git a/gui/src/i18n/zh-TW.ts b/gui/src/i18n/zh-TW.ts
index f8aee1a7a86..670f571c3c1 100644
--- a/gui/src/i18n/zh-TW.ts
+++ b/gui/src/i18n/zh-TW.ts
@@ -587,6 +587,18 @@ export const zhTW: Record<TKey, string> = {
   "models.customAdd": "新增自訂模型",
   "models.customAddTitle": "新增自訂模型 — {provider}",
   "models.customEditTitle": "編輯自訂模型 — {provider}",
+  "models.settingsTitle": "編輯模型 — {model}",
+  "models.settingsSaved": "已儲存 {model} 的模型設定",
+  "models.settingsSaveFailed": "無法儲存模型設定。",
+  "models.settingsRefreshFailed": "已儲存，但模型清單未能重新載入。重新開啟該列即可看到已存的值。",
+  "models.settingsDefaultEffort": "預設檔位",
+  "models.settingsModalitiesInherit": "未覆蓋 — 目前依上游宣告：{modalities}",
+  "models.settingsModalitiesUnknown": "未宣告",
+  "models.settingsRestore": "還原",
+  "models.settingsRestoreHint": "清除這個模型上的全部覆蓋，回到程式計算值。",
+  "models.settingsRestoreConfirm": "把 {model} 還原為程式計算值？這會清除它的上下文視窗、輸入模態與推理覆蓋。",
+  "models.settingsRestored": "{model} 已還原為程式計算值",
+  "models.settingsNothingToRestore": "{model} 沒有覆蓋，已經是程式計算值",
   "models.customAdded": "已新增自訂模型",
   "models.customUpdated": "已更新自訂模型",
   "models.customDeleted": "已刪除自訂模型",
diff --git a/gui/src/i18n/zh.ts b/gui/src/i18n/zh.ts
index 0e740414da5..3d0dfc424b5 100644
--- a/gui/src/i18n/zh.ts
+++ b/gui/src/i18n/zh.ts
@@ -731,6 +731,18 @@ export const zh: Record<TKey, string> = {
   "models.customAdd": "添加自定义模型",
   "models.customAddTitle": "添加自定义模型 — {provider}",
   "models.customEditTitle": "编辑自定义模型 — {provider}",
+  "models.settingsTitle": "编辑模型 — {model}",
+  "models.settingsSaved": "已保存 {model} 的模型设置",
+  "models.settingsSaveFailed": "无法保存模型设置。",
+  "models.settingsRefreshFailed": "已保存，但模型列表未能重新加载。重新打开该行即可看到已存的值。",
+  "models.settingsDefaultEffort": "默认档位",
+  "models.settingsModalitiesInherit": "未覆盖 — 当前按上游声明：{modalities}",
+  "models.settingsModalitiesUnknown": "未声明",
+  "models.settingsRestore": "恢复",
+  "models.settingsRestoreHint": "清除这个模型上的全部覆盖，回到程序计算值。",
+  "models.settingsRestoreConfirm": "把 {model} 恢复为程序计算值？这会清除它的上下文窗口、输入模态与推理覆盖。",
+  "models.settingsRestored": "{model} 已恢复为程序计算值",
+  "models.settingsNothingToRestore": "{model} 没有覆盖，已经是程序计算值",
   "models.customAdded": "已添加自定义模型",
   "models.customUpdated": "已更新自定义模型",
   "models.customDeleted": "已删除自定义模型",
diff --git a/gui/src/pages/Models.tsx b/gui/src/pages/Models.tsx
index 596d76a2ac1..cfd1d89f057 100644
--- a/gui/src/pages/Models.tsx
+++ b/gui/src/pages/Models.tsx
@@ -2,6 +2,7 @@ import { CodexStaleBanner } from "../components/codex-stale-banner";
 import ModelCatalogSettingsPanels from "../components/ModelCatalogSettingsPanels";
 import ModelDisplayNameDialog from "../components/ModelDisplayNameDialog";
 import ModelPriceDialog from "../components/ModelPriceDialog";
+import ModelSettingsDialog from "../components/ModelSettingsDialog";
 import { fetchCodexAppServerState } from "../codex-app-server-state";
 import type { AppServerStateOutcome } from "../codex-app-server-state";
 import { useCodexRestart } from "../use-codex-restart";
@@ -361,6 +362,7 @@ export default function Models({ apiBase, restartEpoch = 0, connected = false, c
   const [displayNameModel, setDisplayNameModel] = useState<ModelRow | null>(null);
   const [priceModel, setPriceModel] = useState<ModelRow | null>(null);
   const priceTriggerRef = useRef<HTMLButtonElement | null>(null);
+  const [settingsModel, setSettingsModel] = useState<ModelRow | null>(null);
   const [displayNameSaving, setDisplayNameSaving] = useState(false);
   const [displayNameRequestError, setDisplayNameRequestError] = useState<string | null>(null);
   const [displayNameRecovery, setDisplayNameRecovery] = useState<{
@@ -1786,6 +1788,7 @@ export default function Models({ apiBase, restartEpoch = 0, connected = false, c
                          </button>
                        </>
                      )}
+                     {!m.native && !m.custom && m.provider !== "combo" && <button type="button" className="btn btn-ghost btn-sm text-caption models-display-name-trigger" aria-haspopup="dialog" aria-label={t("models.settingsTitle", { model: m.namespaced })} onClick={() => setSettingsModel(m)}>{t("models.customEdit")}</button>}
                      {!m.custom && recentIds.has(m.id) && <span className="badge badge-amber">{t("models.newBadge")}</span>}
                      {m.contextCapped && <span className="models-chip muted mono text-caption">{t("models.contextCappedValue", { value: fmtK(m.contextCap ?? contextCapValue) })}</span>}
                    </div>
@@ -2774,6 +2777,11 @@ export default function Models({ apiBase, restartEpoch = 0, connected = false, c
           }}
         />
       )}
+      {settingsModel && (
+        <ModelSettingsDialog key={`${apiBase}/${settingsModel.namespaced}`} row={settingsModel} apiBase={apiBase}
+          onRefresh={signal => load(true, signal)} onFeedback={publishFeedback}
+          onClose={() => setSettingsModel(null)} />
+      )}
     </>
   );
 
diff --git a/gui/src/pages/models-shared.ts b/gui/src/pages/models-shared.ts
index acc694e6bea..5a9b2ece905 100644
--- a/gui/src/pages/models-shared.ts
+++ b/gui/src/pages/models-shared.ts
@@ -54,8 +54,22 @@ export interface ModelRow {
   contextWindow?: number;
   contextCap?: number;
   contextCapped?: boolean;
-  /** Stored custom-row override (not the inherited ladder); only present on custom rows. */
+  /**
+   * Stored custom-row override, or — on a routed row — the ladder that actually applies to it,
+   * resolved from the config and the registry. A routed row carries it because the per-model
+   * editor needs the answer rather than the absence of one.
+   */
   reasoningEfforts?: string[];
+  /** The level a request inherits when it names none; absent when nothing pins one. */
+  defaultReasoningEffort?: string;
+  /**
+   * The stored modality declaration, which is NOT the row's own `inputModalities`: that one is
+   * the catalog value. An editor has to pre-fill from this one, or it shows what the provider
+   * published while writing something else, and every save reads back as "nothing changed".
+   */
+  inputModalitiesDeclared?: string[];
+  /** True when the config really changes this model's reasoning, decided by value, not by key. */
+  reasoningOverridden?: boolean;
 }
 
 /** The pricing shape both Free-only consumers read; keeps the helpers usable from either page. */
diff --git a/gui/tests/model-settings-dialog.test.tsx b/gui/tests/model-settings-dialog.test.tsx
new file mode 100644
index 00000000000..d1821d820bd
--- /dev/null
+++ b/gui/tests/model-settings-dialog.test.tsx
@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Window } from "happy-dom";
+import { act } from "react";
+import type { Root } from "react-dom/client";
+import { clearClientResourceStoresForTests } from "../src/client-resource";
+import { LanguageProvider } from "../src/i18n/provider";
+import Models from "../src/pages/Models";
+import type { ModelRow } from "../src/pages/models-shared";
+
+/**
+ * The per-model settings dialog, driven through the Models page so the row button, the dialog and
+ * the request it sends are exercised as one path.
+ *
+ * The two properties worth pinning are both about what the form SHOWS versus what it WRITES: the
+ * modality boxes pre-fill from the stored declaration rather than the catalog value, and a save
+ * submits only the axis the operator touched. Either one inverted makes the row look unchanged
+ * after a successful write, which is the failure this dialog was written to fix.
+ */
+type Mutation = Record<string, unknown>;
+
+describe("Models per-model settings dialog", () => {
+  const globals = [
+    "document", "window", "navigator", "localStorage", "sessionStorage",
+    "IS_REACT_ACT_ENVIRONMENT", "fetch", "setInterval", "clearInterval",
+  ] as const;
+  let previousGlobals: Record<(typeof globals)[number], PropertyDescriptor | undefined>;
+  let testWindow: Window;
+  let container: HTMLElement;
+  let root: Root | null;
+  let rows: ModelRow[];
+  let mutations: Mutation[];
+  let settingsResponse: ((body: Mutation) => Response) | null;
+
+  beforeEach(() => {
+    clearClientResourceStoresForTests();
+    previousGlobals = Object.fromEntries(globals.map(key => [key, Object.getOwnPropertyDescriptor(globalThis, key)])) as typeof previousGlobals;
+    testWindow = new Window({ url: "http://localhost/#models" });
+    Object.defineProperties(globalThis, {
+      document: { configurable: true, value: testWindow.document },
+      window: { configurable: true, value: testWindow },
+      navigator: { configurable: true, value: testWindow.navigator },
+      localStorage: { configurable: true, value: testWindow.localStorage },
+      sessionStorage: { configurable: true, value: testWindow.sessionStorage },
+      IS_REACT_ACT_ENVIRONMENT: { configurable: true, value: true },
+      setInterval: { configurable: true, value: () => 1 },
+      clearInterval: { configurable: true, value: () => {} },
+    });
+    rows = [
+      {
+        provider: "vendor-demo",
+        id: "chat-large",
+        namespaced: "vendor-demo/chat-large",
+        disabled: false,
+        contextWindow: 200_000,
+        // What the provider published, versus what the operator stored. The dialog must show the
+        // second one; showing the first is how a save came back as "nothing changed".
+        inputModalities: ["text", "image"],
+        inputModalitiesDeclared: ["text"],
+        reasoningEfforts: ["low", "medium", "high"],
+        defaultReasoningEffort: "medium",
+        reasoningOverridden: false,
+      },
+      { provider: "vendor-demo", id: "vendor/custom", namespaced: "vendor-demo/vendor/custom", disabled: false, custom: true, customId: "custom-1" },
+      { provider: "openai", id: "gpt-5.5", namespaced: "openai/gpt-5.5", disabled: false, native: true },
+      { provider: "combo", id: "balanced", namespaced: "combo/balanced", disabled: false },
+    ];
+    const providers = [
+      { name: "vendor-demo", liveModels: false, models: ["chat-large", "vendor/custom"] },
+      { name: "openai", liveModels: false, models: ["gpt-5.5"] },
+    ];
+    mutations = [];
+    settingsResponse = null;
+    testWindow.localStorage.setItem("ocx-lang", "en");
+    testWindow.localStorage.setItem("ocx-models-collapsed:v2", JSON.stringify([]));
+    testWindow.sessionStorage.setItem("ocx.models.catalog.v1:http://localhost", JSON.stringify({
+      models: rows, providers, selectedModels: {}, disabled: [], contextCaps: {}, contextCapValue: 350_000,
+    }));
+    globalThis.fetch = (async (input, init) => {
+      const url = String(input);
+      if (url.endsWith("/api/model-settings")) {
+        const body = JSON.parse(String(init?.body)) as Mutation;
+        mutations.push(body);
+        if (settingsResponse) return settingsResponse(body);
+        return Response.json({ ok: true, provider: body.provider, modelId: body.modelId, changed: true });
+      }
+      if (url.endsWith("/api/models")) return Response.json(rows);
+      if (url.endsWith("/api/providers")) return Response.json(providers);
+      if (url.endsWith("/api/selected-models")) return Response.json({ selected: {} });
+      if (url.endsWith("/api/provider-context-caps")) return Response.json({ caps: {} });
+      if (url.endsWith("/api/aliases")) return Response.json({ providers: {}, models: {}, defaults: { global: false, providers: {} } });
+      if (url.endsWith("/api/combos")) return Response.json({ combos: [] });
+      if (url.endsWith("/api/shadow-call-settings")) return Response.json({ enabled: false, model: "" });
+      if (url.endsWith("/api/v2")) return Response.json({ enabled: false, agentsMaxThreadsConflict: false, multiAgentMode: "default" });
+      return new Response(null, { status: 404 });
+    }) as typeof fetch;
+    container = testWindow.document.createElement("div");
+    testWindow.document.body.appendChild(container as never);
+    root = null;
+  });
+
+  afterEach(async () => {
+    clearClientResourceStoresForTests();
+    if (root) await act(async () => root!.unmount());
+    testWindow.close();
+    for (const key of globals) {
+      const descriptor = previousGlobals[key];
+      if (descriptor) Object.defineProperty(globalThis, key, descriptor);
+      else Reflect.deleteProperty(globalThis, key);
+    }
+  });
+
+  async function flush() {
+    await act(async () => { await new Promise(resolve => testWindow.setTimeout(resolve, 0)); });
+  }
+
+  async function mount() {
+    const { createRoot } = await import("react-dom/client");
+    await act(async () => {
+      root = createRoot(container);
+      root.render(<LanguageProvider><Models apiBase="http://localhost" /></LanguageProvider>);
+    });
+    await flush();
+  }
+
+  function trigger(model = "vendor-demo/chat-large"): HTMLButtonElement | null {
+    return container.querySelector<HTMLButtonElement>(`[aria-label="Edit model — ${model}"]`);
+  }
+
+  function dialog(): HTMLElement | null {
+    return container.querySelector<HTMLElement>("dialog");
+  }
+
+  function dialogButton(label: string): HTMLButtonElement | undefined {
+    return [...container.querySelectorAll<HTMLButtonElement>("dialog button")].find(node => node.textContent === label);
+  }
+
+  function checkboxes(): HTMLInputElement[] {
+    return [...container.querySelectorAll<HTMLInputElement>("dialog input[type=checkbox]")];
+  }
+
+  async function open(model?: string) {
+    await act(async () => trigger(model)!.click());
+    await flush();
+  }
+
+  async function click(label: string) {
+    await act(async () => dialogButton(label)!.click());
+    await flush();
+  }
+
+  test("only a routed row offers the editor", async () => {
+    await mount();
+    expect(container.querySelectorAll('[aria-label^="Edit model — "]')).toHaveLength(1);
+    expect(trigger("vendor-demo/vendor/custom")).toBeNull();
+    expect(trigger("openai/gpt-5.5")).toBeNull();
+    expect(trigger("combo/balanced")).toBeNull();
+  });
+
+  test("the dialog shows the stored declaration, not the catalog value", async () => {
+    await mount();
+    await open();
+    const boxes = checkboxes();
+    // text, image, audio, then the reasoning override — image stays unticked even though the
+    // catalog advertises it, because the declaration is what this form writes.
+    expect(boxes.slice(0, 3).map(box => box.checked)).toEqual([true, false, false]);
+    expect(boxes[3]!.checked).toBe(false);
+    expect(dialog()!.textContent).toContain("vendor-demo/chat-large");
+    // A declaration exists, so the "following the upstream declaration" hint must stay away:
+    // it describes the undeclared state, and showing it here would contradict the ticked box.
+    expect(dialog()!.textContent).not.toContain("upstream declaration");
+  });
+
+  test("an undeclared model ticks nothing and names what it is following instead", async () => {
+    delete rows[0]!.inputModalitiesDeclared;
+    await mount();
+    await open();
+    expect(checkboxes().slice(0, 3).map(box => box.checked)).toEqual([false, false, false]);
+    expect(dialog()!.textContent).toContain("text, image");
+  });
+
+  test("a save submits only the axis the operator touched", async () => {
+    await mount();
+    await open();
+    const image = checkboxes()[1]!;
+    await act(async () => image.click());
+    await click("Apply");
+    expect(mutations).toEqual([{ provider: "vendor-demo", modelId: "chat-large", inputModalities: ["text", "image"] }]);
+    expect(dialog()).toBeNull();
+  });
+
+  test("restore clears every axis, and says so when there was nothing to clear", async () => {
+    await mount();
+    settingsResponse = body => Response.json({ ok: true, provider: body.provider, modelId: body.modelId, changed: false });
+    await open();
+    await click("Restore");
+    // The confirmation is a second dialog on the body, so answer the one it just appended.
+    const confirm = [...testWindow.document.querySelectorAll("dialog")].at(-1)!;
+    const accept = [...confirm.querySelectorAll("button")].find(node => node.textContent === "Restore")!;
+    await act(async () => accept.click());
+    await flush();
+    expect(mutations).toEqual([{
+      provider: "vendor-demo",
+      modelId: "chat-large",
+      contextWindow: null,
+      inputModalities: null,
+      reasoningEfforts: null,
+      defaultReasoningEffort: null,
+    }]);
+    expect(dialog()).toBeNull();
+    expect(container.textContent).toContain("carries no overrides");
+  });
+});
diff --git a/scripts/test-layout/layout.json b/scripts/test-layout/layout.json
index 53bcb676449..17f802faa59 100644
--- a/scripts/test-layout/layout.json
+++ b/scripts/test-layout/layout.json
@@ -534,7 +534,7 @@
     "cli-models-free-only.test.ts": "cli",
     "cli-models-price.test.ts": "cli",
     "cli-models-reasoning.test.ts": "cli",
-    "cli-models-runtime-dispatch.test.ts": "cli",
+    "cli-models-runtime-dispatch.test.ts": "cli", "cli-models-set.test.ts": "cli",
     "cli-models.test.ts": "cli",
     "cli-native-profile.test.ts": "cli",
     "cli-observe-logs.test.ts": "cli",
@@ -1239,7 +1239,7 @@
     "model-pinned-effort.test.ts": "codex-integration",
     "model-presets.test.ts": "providers",
     "model-rename-migration.test.ts": "providers",
-    "model-selection-guidance.test.ts": "cli",
+    "model-selection-guidance.test.ts": "cli", "model-settings-management-api.test.ts": "server",
     "model-visibility-management-api.test.ts": "codex-integration",
     "models-feedback-callback.test.ts": "gui",
     "models-free-filter.test.ts": "gui",
diff --git a/skills/ocx/references/01_management_surface.md b/skills/ocx/references/01_management_surface.md
index 49f91a2ab0a..93e7564d1be 100644
--- a/skills/ocx/references/01_management_surface.md
+++ b/skills/ocx/references/01_management_surface.md
@@ -598,6 +598,28 @@ JSON mode: `payload`.
 
 - Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved.
 
+### `ocx models set`
+
+Save per-model overrides for a routed model, or clear them back to the computed values.
+
+| Method | Route |
+|---|---|
+| PUT | `/api/model-settings` |
+
+| Flag | Value | Meaning |
+|---|---|---|
+| `--context-window` | string | Context window in tokens; 0 or - clears the override. |
+| `--modalities` | string | Comma-separated text,image,audio; - clears the override. |
+| `--reasoning-efforts` | string | Comma-separated ladder; "" for no reasoning, - to inherit. |
+| `--default-reasoning-effort` | string | Ladder member a request inherits when it omits one; - to inherit. |
+| `--reset` | boolean | Clear every override on this model; cannot be combined with the options above. |
+| `--json` | boolean | Emit the saved state as JSON. |
+
+JSON mode: `envelope`.
+
+- Addresses a routed model as provider/model. The native openai lane and combos have no per-model overrides.
+- Unlike ocx models edit, which changes a custom model's own definition, this edits a row that already exists.
+
 ### `ocx hub invite`
 
 Mint a single-use pairing code on a hub and print the exact `ocx connect` line for one more machine.
@@ -1158,6 +1180,6 @@ JSON mode: `payload`.
 
 ## Counts
 
-- declared capabilities: 65
-- of those, state-changing: 35
+- declared capabilities: 66
+- of those, state-changing: 36
 - head-resolved invocations: 2
diff --git a/src/cli/capabilities.ts b/src/cli/capabilities.ts
index fd269ae8551..390b928503e 100644
--- a/src/cli/capabilities.ts
+++ b/src/cli/capabilities.ts
@@ -240,6 +240,25 @@ export const CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["Uses the exact upstream model ID after the first slash. Omitted cache rates default to zero; sibling model prices are preserved."],
   },
+  {
+    command: ["models", "set"],
+    summary: "Save per-model overrides for a routed model, or clear them back to the computed values.",
+    routes: [{ method: "PUT", path: "/api/model-settings" }],
+    flags: [
+      { name: "--context-window", value: "string", summary: "Context window in tokens; 0 or - clears the override." },
+      { name: "--modalities", value: "string", summary: "Comma-separated text,image,audio; - clears the override." },
+      { name: "--reasoning-efforts", value: "string", summary: "Comma-separated ladder; \"\" for no reasoning, - to inherit." },
+      { name: "--default-reasoning-effort", value: "string", summary: "Ladder member a request inherits when it omits one; - to inherit." },
+      { name: "--reset", value: "boolean", summary: "Clear every override on this model; cannot be combined with the options above." },
+      { name: "--json", value: "boolean", summary: "Emit the saved state as JSON." },
+    ],
+    mutates: true,
+    json: "envelope",
+    details: [
+      "Addresses a routed model as provider/model. The native openai lane and combos have no per-model overrides.",
+      "Unlike ocx models edit, which changes a custom model's own definition, this edits a row that already exists.",
+    ],
+  },
   {
     command: ["status"],
     summary: "Proxy status, injection state, and version skew between this CLI and the running proxy.",
diff --git a/src/cli/models-runtime-subcommands.ts b/src/cli/models-runtime-subcommands.ts
index 4aa6d7b77a8..d9ae5e20116 100644
--- a/src/cli/models-runtime-subcommands.ts
+++ b/src/cli/models-runtime-subcommands.ts
@@ -18,6 +18,7 @@ export const MODELS_RUNTIME_SUBCOMMANDS = [
   "price",
   "set-price",
   "edit",
+  "set",
   "enable",
   "disable",
   "provider",
diff --git a/src/cli/models-runtime.ts b/src/cli/models-runtime.ts
index ad753f3002f..08683f43e8f 100644
--- a/src/cli/models-runtime.ts
+++ b/src/cli/models-runtime.ts
@@ -31,6 +31,10 @@ const USAGE = `Usage:
       [--context-window <tokens|0>] [--modalities <text,image,audio|->]
       [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra|->]
       [--default-reasoning-effort <level|->] [--json]
+  ocx models set <provider/model> [--context-window <tokens|0|->]
+      [--modalities <text,image,audio|->]
+      [--reasoning-efforts <none,minimal,low,medium,high,xhigh,max,ultra|"">|->]
+      [--default-reasoning-effort <level|->] [--reset] [--json]
   ocx models <enable|disable> <provider/model|native-model> [--native] [--json]
   ocx models provider <name> <on|off> [--json]
   ocx models selected <provider> [--set <id,id...>|--clear] [--json]
@@ -245,6 +249,82 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`Updated custom model ${id}.`]);
 }
 
+/**
+ * Per-model overrides on a routed row: the twin of `ocx models edit` for rows that already
+ * exist, rather than for a custom definition.
+ *
+ * Every option has a clear spelling instead of an empty-value sentinel, because the API treats
+ * `null` as "hand this fact back to the registry, the catalog and the provider default". That is
+ * a different intent from storing a value that merely looks blank, and collapsing the two is how
+ * an override outlives the data it was copied from.
+ */
+async function setModelSettings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const selector = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const reset = takeFlag(args, "--reset");
+  if (!selector) throw new CliUsageError("model selector is required", USAGE);
+  const contextRaw = takeOption(args, "--context-window");
+  const modalitiesRaw = takeOption(args, "--modalities");
+  const reasoningEffortsRaw = takeOption(args, "--reasoning-efforts");
+  const defaultEffortRaw = takeOption(args, "--default-reasoning-effort");
+  rejectArgs(args, USAGE);
+  const target = parseSelector(selector, false);
+  if (target.native) {
+    throw new CliUsageError(
+      "model settings address a routed model; use provider/model (the native openai lane has no per-model overrides)",
+      USAGE,
+    );
+  }
+  const patch: Record<string, unknown> = {};
+  if (contextRaw !== undefined) {
+    const raw = contextRaw.trim();
+    if (raw === "-") patch.contextWindow = null;
+    else {
+      const value = Number(raw.replace(/[_,]/g, ""));
+      if (!Number.isInteger(value) || value < 0) {
+        throw new CliUsageError("--context-window must be an integer >= 0 (0 or - clears the override)", USAGE);
+      }
+      patch.contextWindow = value === 0 ? null : value;
+    }
+  }
+  if (modalitiesRaw !== undefined) patch.inputModalities = modalitiesRaw.trim() === "-" ? null : csv(modalitiesRaw);
+  if (reasoningEffortsRaw !== undefined) {
+    // "-" restores inheritance by clearing the stored ladder (null); "" stores an explicit empty
+    // ladder, which is the "this model does not reason" override. Embedded blank CSV members
+    // (`low,,high`) are malformed and rejected rather than normalized away.
+    const trimmed = reasoningEffortsRaw.trim();
+    if (trimmed === "-") {
+      patch.reasoningEfforts = null;
+    } else if (trimmed === "") {
+      patch.reasoningEfforts = [];
+    } else {
+      const values = trimmed.split(",").map(value => value.trim());
+      if (values.some(value => value === "")) {
+        throw new CliUsageError("--reasoning-efforts must be comma-separated values from none, minimal, low, medium, high, xhigh, max, ultra (\"\" for no reasoning, \"-\" to inherit)", USAGE);
+      }
+      patch.reasoningEfforts = values;
+    }
+  }
+  if (defaultEffortRaw !== undefined) patch.defaultReasoningEffort = defaultEffortRaw.trim() === "-" ? null : defaultEffortRaw.trim();
+  if (reset) {
+    if (Object.keys(patch).length > 0) {
+      throw new CliUsageError("--reset clears every override and cannot be combined with other options", USAGE);
+    }
+    for (const key of ["contextWindow", "inputModalities", "reasoningEfforts", "defaultReasoningEffort"]) patch[key] = null;
+  }
+  if (Object.keys(patch).length === 0) throw new CliUsageError("at least one setting or --reset is required", USAGE);
+  const result = await runtimeRequest<{ changed?: boolean }>("/api/model-settings", {
+    method: "PUT",
+    body: JSON.stringify({ provider: target.provider, modelId: target.id, ...patch }),
+  }, deps);
+  printData(result, wantsJson, [
+    result?.changed === false
+      ? selector + " carries no overrides; it already resolves to the computed values."
+      : "Updated model settings for " + selector + ".",
+  ]);
+}
+
 function parseSelector(selector: string, forceNative: boolean): { provider: string; id: string; native: boolean } {
   if (forceNative || !selector.includes("/")) return { provider: "openai", id: selector, native: true };
   const slash = selector.indexOf("/");
@@ -475,6 +555,7 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "price") action = () => price(false, argv, deps);
   else if (sub === "set-price") action = () => price(true, argv, deps);
   else if (sub === "edit") action = () => edit(argv, deps);
+  else if (sub === "set") action = () => setModelSettings(argv, deps);
   else if (sub === "enable") action = () => visibility(true, argv, deps);
   else if (sub === "disable") action = () => visibility(false, argv, deps);
   else if (sub === "provider") action = () => providerVisibility(argv, deps);
diff --git a/src/server/management/model-routes.ts b/src/server/management/model-routes.ts
index 42364b3d579..88f0ab6d72c 100644
--- a/src/server/management/model-routes.ts
+++ b/src/server/management/model-routes.ts
@@ -11,9 +11,17 @@ import { shouldInjectApiAuthHeader } from "../../codex/loopback-target";
  * be handed back to the GUI and CLI as if it were real, and the offline `ocx models add` path
  * already refuses it. Validate at ingress so all three paths agree.
  */
-const ALLOWED_INPUT_MODALITIES = new Set(["text", "image", "audio"]);
+/**
+ * The modalities a declaration may carry. `video` is missing on purpose: the wire carries text
+ * and image parts, so advertising it would be a promise no request path can keep.
+ */
+type DeclaredInputModality = NonNullable<ModelCapabilities["inputModalities"]>[number];
+
+// A plain string set on purpose: the lookup runs against unvalidated input, and the enum lives in
+// the return type below, where the cast is the validator's stated guarantee.
+const ALLOWED_INPUT_MODALITIES: ReadonlySet<string> = new Set(["text", "image", "audio"]);
 
-function readInputModalities(raw: unknown): { values?: string[]; error?: string } {
+function readInputModalities(raw: unknown): { values?: DeclaredInputModality[]; error?: string } {
   if (raw === undefined) return {};
   if (!Array.isArray(raw)) return { error: "inputModalities must be an array" };
   // Reject non-strings rather than filtering them out. Dropping them silently accepted a
@@ -28,7 +36,7 @@ function readInputModalities(raw: unknown): { values?: string[]; error?: string
   if (rejected.length > 0) {
     return { error: `unsupported input modality: ${rejected.join(", ")} (allowed: text, image, audio)` };
   }
-  return { values: raw as string[] };
+  return { values: raw as DeclaredInputModality[] };
 }
 
 /**
@@ -131,7 +139,7 @@ import {
   setDebugSettings,
   type DebugFlag,
 } from "../../lib/debug-settings";
-import type { OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, ProviderCostOverlay } from "../../types";
+import type { ModelCapabilities, OcxClaudeCodeConfig, OcxConfig, OcxCustomModel, OcxProviderConfig, ProviderCostOverlay } from "../../types";
 import { drainAndShutdown } from "../lifecycle";
 import { filterRequestLogs, getRequestLogEntries, type RequestLogEntry } from "../request-log";
 import { estimateComboCost, estimateRequestCost, normalizeCostTokens, tokensPerSecond } from "../../usage/cost";
@@ -157,7 +165,7 @@ import type {
 import { isPlainRecord, parseDebugLogQuery, tokPerSecondResult, unavailableCostReason, costResult, requestLogDto, stripRegistryOnlyStaticHeaders, fetchAllModels } from "./shared";
 import type { MetricUnavailableReason, TokPerSecondResult, CostEstimateReason, CostResult, MetricSource } from "./shared";
 import type { ManagementContext } from "./context";
-import { listManagementModelRows, loadExportModels } from "./model-rows";
+import { effectiveModelReasoningEfforts, inheritedModelReasoningEfforts, listManagementModelRows, loadExportModels } from "./model-rows";
 import { initialModelSelectionPending } from "../../providers/initial-model-selection";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import {
@@ -733,6 +741,179 @@ export async function handleModelRoutes(ctx: ManagementContext): Promise<Respons
     return jsonResponse(config.customModels ?? []);
   }
 
+  /*
+   * Per-model overrides for a routed row, addressed by provider + upstream model id.
+   *
+   * Deliberately not a custom model. A custom model is a row the operator declares; this edits
+   * facts about a row that already exists, through the provider-level per-model maps the runtime
+   * already reads. Creating a custom model to change one field would replace the row's identity
+   * and its discovery provenance, which is the opposite of what an edit means.
+   *
+   * Every field is optional and `null` CLEARS the declaration rather than writing a default: that
+   * is what hands the fact back to the registry, the catalog and the provider, instead of pinning
+   * today's answer as an override that silently outlives the data it came from.
+   *
+   * Display name is not here on purpose. The row already has a dedicated editor for it
+   * (PUT /api/providers/{provider}/model-display-names) with its own provenance display; a second
+   * control writing the same key is two statements that can drift, and this endpoint's job is the
+   * capability axes nothing else edits.
+   */
+  if (url.pathname === "/api/model-settings" && req.method === "PUT") {
+    let parsedBody: unknown;
+    try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
+    if (!isPlainRecord(parsedBody)) return jsonResponse({ error: "invalid model settings request" }, 400);
+    const body = parsedBody;
+    const provider = typeof body.provider === "string" ? body.provider.trim() : "";
+    const modelId = typeof body.modelId === "string" ? body.modelId.trim() : "";
+    if (!provider || !modelId) return jsonResponse({ error: "provider and modelId are required" }, 400);
+    if (!isValidProviderName(provider) || !hasOwnProvider(config.providers, provider)) {
+      return jsonResponse({ error: "unknown model settings provider" }, 400);
+    }
+    // "openai" is the native passthrough lane and "combo" is a synthetic row: neither is a
+    // provider whose per-model maps the runtime consults for these facts.
+    if (provider === "openai" || provider === "combo") {
+      return jsonResponse({ error: "model settings are only available for routed providers" }, 400);
+    }
+
+    const providerConfig = config.providers[provider];
+    const storedLadder = providerConfig.modelReasoningEfforts?.[modelId];
+
+    let contextWindow: number | null | undefined;
+    if (body.contextWindow !== undefined) {
+      if (body.contextWindow === null) contextWindow = null;
+      else if (typeof body.contextWindow === "number" && Number.isFinite(body.contextWindow) && body.contextWindow > 0) {
+        contextWindow = Math.floor(body.contextWindow);
+      } else return jsonResponse({ error: "contextWindow must be a positive number or null" }, 400);
+    }
+    let modalities: DeclaredInputModality[] | null | undefined;
+    if (body.inputModalities !== undefined) {
+      if (body.inputModalities === null) modalities = null;
+      else {
+        const parsed = readInputModalities(body.inputModalities);
+        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
+        // An empty array means "cleared", exactly like null: a model that accepts no modality at
+        // all is not a state this surface can express, and storing [] would advertise text-only
+        // through a value the catalog then has to special-case.
+        // Deduplicated before the unchanged check and before the write: `["text","text"]` against
+        // a stored `["text","image"]` passes a length test and an every-member test, so the
+        // operator's edit would be dropped as a no-op; when it did differ, the duplicates would be
+        // persisted as submitted.
+        const unique = parsed.values ? [...new Set(parsed.values)] : [];
+        modalities = unique.length > 0 ? unique : null;
+      }
+    }
+    let ladder: string[] | null | undefined;
+    if (body.reasoningEfforts !== undefined) {
+      if (body.reasoningEfforts === null) ladder = null;
+      else {
+        const parsed = readReasoningEfforts(body.reasoningEfforts);
+        if (parsed.error) return jsonResponse({ error: parsed.error }, 400);
+        ladder = parsed.values ?? [];
+      }
+    }
+    /*
+     * Validated against the ladder this write leaves behind, not the one that happens to be stored:
+     * a caller replacing both in one request must not be rejected for the value it is replacing, and
+     * a default-only request must be judged against the ladder the model actually resolves — which
+     * may be the provider-level, registry, native or catalog one, not only a per-model entry.
+     * `inheritedModelReasoningEfforts` is what the clear case leaves behind: it removes the model's
+     * entry from a copy before resolving, so it answers the post-write state.
+     */
+    const resultingLadder = ladder === undefined
+      ? (Array.isArray(storedLadder) ? storedLadder : effectiveModelReasoningEfforts(config, provider, modelId))
+      : (ladder ?? inheritedModelReasoningEfforts(config, provider, modelId));
+    const defaultEffort = readDefaultReasoningEffort(body.defaultReasoningEffort, resultingLadder);
+    if (defaultEffort.error) return jsonResponse({ error: defaultEffort.error }, 400);
+
+    let changed = false;
+    const writePerModel = (
+      key: "modelContextWindows" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts",
+      value: unknown,
+    ) => {
+      if (value === undefined) return;
+      const bag = providerConfig as unknown as Record<string, unknown>;
+      const record = { ...((bag[key] as Record<string, unknown> | undefined) ?? {}) };
+      const present = Object.prototype.hasOwnProperty.call(record, modelId);
+      if (value === null) {
+        if (!present) return;
+        delete record[modelId];
+        changed = true;
+      } else {
+        if (present && JSON.stringify(record[modelId]) === JSON.stringify(value)) return;
+        record[modelId] = value;
+        changed = true;
+      }
+      // An emptied map is removed rather than left as {}. The maps are optional config fields, and
+      // an empty one is indistinguishable from a configured-but-blank state to every reader.
+      if (Object.keys(record).length === 0) delete bag[key];
+      else bag[key] = record;
+    };
+    writePerModel("modelContextWindows", contextWindow);
+    writePerModel("modelReasoningEfforts", ladder);
+    if (body.defaultReasoningEffort !== undefined) {
+      writePerModel("modelDefaultReasoningEfforts", defaultEffort.value === undefined ? null : defaultEffort.value);
+    } else if (ladder !== undefined) {
+      /*
+       * A ladder write can strand a stored default that the model can no longer select, and the
+       * catalog would then publish a default outside its own ladder. The caller said nothing about
+       * the default, so only one that cannot survive is cleared. With `ladder === null` the override
+       * is gone and the ladder to test against is the inherited one — read from the config after the
+       * write, which no longer carries the removed entry.
+       */
+      const storedDefault = providerConfig.modelDefaultReasoningEfforts?.[modelId];
+      const effectiveLadder = ladder ?? effectiveModelReasoningEfforts(config, provider, modelId);
+      if (typeof storedDefault === "string" && !(effectiveLadder ?? []).includes(storedDefault)) {
+        writePerModel("modelDefaultReasoningEfforts", null);
+      }
+    }
+    if (modalities !== undefined) {
+      const capabilities = { ...(providerConfig.modelCapabilities ?? {}) };
+      const row = { ...(capabilities[modelId] ?? {}) };
+      const declared = Array.isArray(row.inputModalities) ? [...row.inputModalities] : undefined;
+      const unchanged = modalities === null
+        ? declared === undefined
+        : declared !== undefined
+          && declared.length === modalities.length
+          && modalities.every(modality => declared.includes(modality));
+      if (!unchanged) {
+        changed = true;
+        if (modalities === null) delete row.inputModalities;
+        else row.inputModalities = modalities;
+        if (Object.keys(row).length === 0) delete capabilities[modelId];
+        else capabilities[modelId] = row;
+        if (Object.keys(capabilities).length === 0) delete providerConfig.modelCapabilities;
+        else providerConfig.modelCapabilities = capabilities;
+      }
+    }
+
+    const state = {
+      ok: true as const,
+      provider,
+      modelId,
+      contextWindow: providerConfig.modelContextWindows?.[modelId] ?? null,
+      inputModalities: providerConfig.modelCapabilities?.[modelId]?.inputModalities ?? null,
+      reasoningEfforts: providerConfig.modelReasoningEfforts?.[modelId] ?? null,
+      defaultReasoningEffort: providerConfig.modelDefaultReasoningEfforts?.[modelId] ?? null,
+    };
+    // `changed: false` is a real answer, not a failure: it is what tells a caller that the model
+    // carries no override to clear, so an editor can say so instead of claiming it restored one.
+    if (!changed) return jsonResponse({ ...state, changed: false });
+    persistConfig(config);
+    /*
+     * Drop this provider's live `/models` cache before converging.
+     *
+     * The gather bakes the resolved hints into the rows it caches, and on a cache hit it re-applies
+     * the config through `clampObservedModelLimits`, where a configured window may only LOWER the
+     * observed one. A raised or cleared override would therefore keep reading back the previous
+     * answer for the whole TTL, and a cleared modality or ladder would keep the baked one. Clearing
+     * the entry is what makes the save visible on the next read, the same reason
+     * `PUT /api/provider-context-caps` clears it per affected provider.
+     */
+    clearModelCache(provider);
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ ...state, changed: true, catalogRefresh });
+  }
+
   if (url.pathname === "/api/custom-models" && req.method === "POST") {
     let parsedBody: unknown;
     try { parsedBody = await readManagementJsonBody(req); } catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid JSON body" }, 400); }
diff --git a/src/server/management/model-rows.ts b/src/server/management/model-rows.ts
index a2964680b73..e4dec3920d4 100644
--- a/src/server/management/model-rows.ts
+++ b/src/server/management/model-rows.ts
@@ -26,12 +26,15 @@ import {
   nativeReasoningEfforts,
   uniqueCatalogModelsForPublicList,
   shouldIncludeAccountBoundNativeOpenAi,
+  catalogModelEfforts,
 } from "../../codex/catalog";
+import { SUPPORTED_NATIVE_OPENAI_SLUGS } from "../../codex/catalog/native-models";
 import type { ExportModel } from "../../clients/config-export";
 import { providerContextCap } from "../../providers/context-cap";
-import { isVisionReasoningEffort } from "../../reasoning-effort";
+import { isVisionReasoningEffort, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { routedSlug, slugEquals } from "../../providers/slug-codec";
 import type { OcxConfig } from "../../types";
+import { enrichProviderFromRegistry } from "../../providers/derive";
 import { ensureCodexEntitlementFreshness } from "../../codex/model-entitlements";
 import { fetchAllModels } from "./shared";
 import { initialModelSelectionPending, pendingModelSelectionProviders } from "../../providers/initial-model-selection";
@@ -56,6 +59,19 @@ export type ManagementModelRow = Partial<CatalogModel> & {
   fastRowAvailable?: boolean;
   displayNameOverride?: string;
   displayNameSource?: "operator" | "provider" | "fallback";
+  /**
+   * The modality declaration a per-model editor writes, read from the same sources the runtime
+   * consults. It is separate from the row's own `inputModalities` because that one is the
+   * CATALOG value: an editor that pre-fills from the catalog while writing the declaration shows
+   * one thing and saves another, so its own writes never appear to take.
+   */
+  inputModalitiesDeclared?: string[];
+  /**
+   * True when the provider config actually CHANGES reasoning for this model. A persisted key is
+   * not proof of an operator edit — OpenCodex itself writes the registry ladder into the provider
+   * config — so this compares values against what the model would inherit anyway.
+   */
+  reasoningOverridden?: boolean;
 };
 
 /** Resolve the exact text and source shown for one routed discovered model. */
@@ -76,6 +92,161 @@ export function effectiveManagementDisplayName(
   return { displayName: catalogModelSlug(model), displayNameSource: "fallback" };
 }
 
+/**
+ * The modality declaration an editor writes, resolved the way the runtime resolves it: an exact
+ * `modelCapabilities` entry first, then the legacy `modelInputModalities` record, both after the
+ * registry has filled in whatever the saved config predates.
+ */
+export function declaredModelInputModalities(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+): string[] | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const enriched = {
+    ...provider,
+    ...(provider.modelInputModalities ? { modelInputModalities: { ...provider.modelInputModalities } } : {}),
+    ...(provider.modelCapabilities ? { modelCapabilities: { ...provider.modelCapabilities } } : {}),
+  };
+  enrichProviderFromRegistry(providerName, enriched);
+  const declared = enriched.modelCapabilities?.[modelId]?.inputModalities
+    ?? modelRecordValue(enriched.modelInputModalities, modelId);
+  return Array.isArray(declared) && declared.length > 0 ? [...declared] : undefined;
+}
+
+/**
+ * The ladder that actually applies to this model: an explicit declaration wins, then the
+ * registry-enriched provider map, then the pinned native OpenAI table for a resold native id,
+ * then the catalog's own effort hints.
+ *
+ * The registry enrichment is not optional. The catalog reads the enriched provider, so a registry
+ * declaration (google-antigravity's `gemini-3.8-flash`, for one) IS the model's ladder; reading
+ * the saved config alone would report no ladder for a model that has one.
+ *
+ * The catalog's own hints are the one source that costs a file read per lookup. `catalogLadders`
+ * is the batched form of it: a roster projection resolves every routed id once and passes the map
+ * down, instead of asking `catalogModelEfforts` per row and re-parsing the same file each time.
+ * Omitting it keeps the single-model behaviour for every other caller.
+ */
+export type CatalogLadderLookup = ReadonlyMap<string, string[]>;
+
+function catalogLadder(ladders: CatalogLadderLookup | undefined, modelId: string): string[] | undefined {
+  return ladders ? ladders.get(modelId) : catalogModelEfforts([modelId]).get(modelId);
+}
+
+export function effectiveModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, declaredEfforts?: string[], catalogLadders?: CatalogLadderLookup): string[] | undefined {
+  // An empty array is a declaration, not an absence: the operator stored "this model has no
+  // reasoning rungs", and falling through to the inherited ladder here would report a ladder the
+  // row does not have and hand it back to the editor on the next refresh.
+  if (Array.isArray(declaredEfforts)) return declaredEfforts;
+  const provider = config.providers[providerName];
+  if (provider) {
+    const enriched = {
+      ...provider,
+      ...(provider.modelReasoningEfforts ? { modelReasoningEfforts: { ...provider.modelReasoningEfforts } } : {}),
+    };
+    enrichProviderFromRegistry(providerName, enriched);
+    const raw = modelRecordValue(enriched.modelReasoningEfforts, modelId) ?? enriched.reasoningEfforts;
+    // Mirrors `configuredReasoningEfforts`, the reader the wire actually uses: a stored array is a
+    // declaration even when it sanitizes down to nothing, and only a missing entry inherits.
+    if (Array.isArray(raw)) return sanitizeCodexReasoningEfforts(raw) ?? [];
+  }
+  // A provider reselling a native OpenAI id inherits that model's pinned ladder.
+  if (SUPPORTED_NATIVE_OPENAI_SLUGS.has(modelId)) {
+    const native = nativeReasoningEfforts(modelId);
+    if (native.length > 0) return native;
+  }
+  const hits = catalogLadder(catalogLadders, modelId);
+  if (hits && hits.length > 0) return hits;
+  return undefined;
+}
+
+export function effectiveModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, declaredDefault?: string, efforts?: string[]): string | undefined {
+  if (declaredDefault) return declaredDefault;
+  const provider = config.providers[providerName];
+  if (provider) {
+    const stored = modelRecordValue(provider.modelDefaultReasoningEfforts, modelId);
+    if (stored) return stored;
+  }
+  if (efforts && efforts.length > 0) {
+    // The default is the ladder's own preference order, not its first entry: a model offering
+    // low..high defaults to medium, and only a ladder that omits it falls back to low.
+    if (efforts.includes("medium")) return "medium";
+    if (efforts.includes("low")) return "low";
+    return efforts[0];
+  }
+  return undefined;
+}
+
+/**
+ * Whether the saved config really overrides reasoning for this model, decided by VALUE rather
+ * than by key presence.
+ *
+ * The distinction is the whole point: OpenCodex writes the registry ladder (and its default) into
+ * the provider config itself, so a bare `hasOwnProperty` test reports every registry-declared
+ * model as hand-edited. An entry that resolves to the same ladder and default the model would
+ * inherit anyway is not an override, and an editor that pre-fills an "override" checkbox from one
+ * claims an edit nobody made.
+ */
+export function reasoningOverrideFor(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): boolean {
+  const provider = config.providers[providerName];
+  if (!provider) return false;
+  const owns = (record: Record<string, unknown> | undefined) =>
+    !!record && Object.prototype.hasOwnProperty.call(record, modelId);
+  const ownsEfforts = owns(provider.modelReasoningEfforts as Record<string, unknown> | undefined);
+  const ownsDefault = owns(provider.modelDefaultReasoningEfforts as Record<string, unknown> | undefined);
+  if (!ownsEfforts && !ownsDefault) return false;
+  if (ownsEfforts) {
+    // `undefined` (nothing known) and `[]` (pinned to no rungs) are different facts, and joining
+    // both to "" would report a pinned-empty ladder as no override at all.
+    const ladderKey = (values: string[] | undefined) => (values === undefined ? null : values.join(","));
+    const effective = effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
+    const inherited = inheritedModelReasoningEfforts(config, providerName, modelId, catalogLadders);
+    if (ladderKey(effective) !== ladderKey(inherited)) return true;
+  }
+  if (ownsDefault) {
+    const effective = effectiveModelDefaultReasoningEffort(config, providerName, modelId);
+    const inherited = inheritedModelDefaultReasoningEffort(config, providerName, modelId, catalogLadders);
+    if (effective !== inherited) return true;
+  }
+  return false;
+}
+
+/** The ladder this model inherits when no per-model override exists. */
+export function inheritedModelReasoningEfforts(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string[] | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const record = provider.modelReasoningEfforts;
+  if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
+    return effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders);
+  }
+  const next = { ...record };
+  delete next[modelId];
+  const stripped = { ...provider, modelReasoningEfforts: next };
+  const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
+  return effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders);
+}
+
+/** The default this model inherits when no per-model default override exists. */
+export function inheritedModelDefaultReasoningEffort(config: OcxConfig, providerName: string, modelId: string, catalogLadders?: CatalogLadderLookup): string | undefined {
+  const provider = config.providers[providerName];
+  if (!provider) return undefined;
+  const record = provider.modelDefaultReasoningEfforts;
+  if (!record || !Object.prototype.hasOwnProperty.call(record, modelId)) {
+    return effectiveModelDefaultReasoningEffort(
+      config, providerName, modelId, undefined, effectiveModelReasoningEfforts(config, providerName, modelId, undefined, catalogLadders),
+    );
+  }
+  const next = { ...record };
+  delete next[modelId];
+  const stripped = { ...provider, modelDefaultReasoningEfforts: next };
+  const view = { ...config, providers: { ...config.providers, [providerName]: stripped } };
+  return effectiveModelDefaultReasoningEffort(
+    view, providerName, modelId, undefined, effectiveModelReasoningEfforts(view, providerName, modelId, undefined, catalogLadders),
+  );
+}
+
 /**
  * The exact row list `/api/models` returns. Extracted so `/api/client-config` exports the
  * models the GUI's Models tab shows — including this function's `disabled` computation,
@@ -190,6 +361,11 @@ export async function listManagementModelRows(
   // Custom metadata wins when a physical live/static row resolves to the same Codex-facing
   // slug, while a combo keeps the same precedence it has in routing and /v1/models.
   const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));
+  // One catalog read for the whole roster. Every `catalogModelEfforts` call parses the catalog
+  // file and scans it once per requested slug, so resolving these per row (and twice per row, as
+  // the guard and the value) re-read the same file thousands of times on a large roster.
+  const routedIds = publicModels.filter(m => m.provider !== "combo").map(m => m.id);
+  const catalogLadders = catalogModelEfforts([...new Set(routedIds)]);
   const dedupedRouted = publicModels.map((m): ManagementModelRow | null => {
     // Codex-facing slug (one "/", slug-codec); disabledModels compares tolerate both forms.
     const namespaced = catalogModelSlug(m);
@@ -197,6 +373,15 @@ export async function listManagementModelRows(
     const contextCap = providerContextCap(config, m.provider);
     const nativeAlias = m.provider === "combo" && m.nativeAlias === true;
     const displayName = effectiveManagementDisplayName(config, m);
+    const routed = m.provider !== "combo";
+    // Resolved once each: the spread below used to evaluate the same helpers again for the guard.
+    const reasoningEfforts = routed
+      ? effectiveModelReasoningEfforts(config, m.provider, m.id, m.reasoningEfforts, catalogLadders)
+      : undefined;
+    const defaultReasoningEffort = routed
+      ? effectiveModelDefaultReasoningEffort(config, m.provider, m.id, m.defaultReasoningEffort, reasoningEfforts)
+      : undefined;
+    const inputModalitiesDeclared = routed ? declaredModelInputModalities(config, m.provider, m.id) : undefined;
     return {
       ...m,
       ...displayName,
@@ -205,6 +390,13 @@ export async function listManagementModelRows(
         (!nativeAlias && stored === namespaced) || slugEquals(stored, m.provider, m.id)
       )),
       ...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
+      // A routed row inherits nothing about reasoning or modalities from the row spread above:
+      // the catalog only carries what discovery reported, so the effective answers are resolved
+      // here, where the config and the registry are both in hand.
+      ...(reasoningEfforts !== undefined ? { reasoningEfforts } : {}),
+      ...(defaultReasoningEffort !== undefined ? { defaultReasoningEffort } : {}),
+      ...(routed ? { reasoningOverridden: reasoningOverrideFor(config, m.provider, m.id, catalogLadders) } : {}),
+      ...(inputModalitiesDeclared !== undefined ? { inputModalitiesDeclared } : {}),
     };
   }).filter((row): row is ManagementModelRow => row !== null);
   // Manual OpenAI rows retain their routed selector but replace the bare dashboard row.
diff --git a/src/server/management/route-registry.ts b/src/server/management/route-registry.ts
index b9b9c4220a8..3a95c07dd57 100644
--- a/src/server/management/route-registry.ts
+++ b/src/server/management/route-registry.ts
@@ -277,6 +277,7 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PUT", path: "/api/disabled-models", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-discovery", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-presets", module: "server/management/model-routes", mutates: true },
+  { method: "PUT", path: "/api/model-settings", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/model-visibility", module: "server/management/model-routes", mutates: true },
   { method: "PUT", path: "/api/selected-models", module: "server/management/model-routes", mutates: true },
   // server/management/native-integration-routes
diff --git a/structure/gui-and-management-api.md b/structure/gui-and-management-api.md
index be59cb022dd..5e602810757 100644
--- a/structure/gui-and-management-api.md
+++ b/structure/gui-and-management-api.md
@@ -227,7 +227,7 @@ per-request first-party callback reads that live object; a failed write leaves i
 | Sidecar/shadow-call settings | `src/server/management/config-routes.ts` — `GET/PUT /api/sidecar-settings` and `GET/PUT /api/shadow-call-settings`. PUT accepts model and backend (web-search union: openai/anthropic/xai/gemini/exa; xAI is live through stored Grok OAuth, while Gemini/Exa remain inert until their executors ship) plus validated `webSearch.xSearch`, optional `webSearch.exaApiKey` (write/clear only — never echoed by GET or the PUT response; redact.ts strips it from logs), `webSearch.reasoning`, `vision.reasoning`, `vision.enabled`, `vision.maxDescriptionsPerTurn`, and `vision.timeoutMs`; the read and PUT-response payload reports model, backend, reasoning, enabled, the vision per-turn limit, and timeout. `timeoutMs` is validated against the runtime integer bounds in `src/vision/timeout-bounds.ts`. Provider/OAuth credentials live in their stores; `exaApiKey` is the one sidecar-owned secret and follows the write-only contract above. Both shadow-call responses also report the resolved `sourceModels` — the prefixes the runtime actually intercepts (`src/lib/shadow-call.ts`, default `gpt-6-luna` and `gpt-5.6-luna`; the retired `gpt-5.4-mini` stays available as an explicit `sourceModels` entry for 0.144.x clients), so no client hard-codes a helper slug that a Codex release can invalidate. PUT refuses a qualified target that only the router's default-provider fallback accepts. Provider disable and delete report the target they leave behind as `dependentShadowIntercept` (`shadowInterceptProviderDependency` in `src/server/management/shadow-call-validation.ts`), and at request time an unresolvable target returns `409 intercept_target_unavailable` before any send (`src/server/responses/shadow-target-availability.ts`); it never falls back to the native source model or the default provider. |
 | Storage | `src/server/management/logs-usage-routes.ts` — `GET /api/storage`, `POST /api/storage/cleanup/preview` and `/api/storage/cleanup`, `GET /api/storage/trash`, `POST /api/storage/trash/restore`, and `GET/PUT /api/storage/cleanup-policy` plus `POST /api/storage/cleanup-policy/run`. `GET /api/storage/cleanup-policy/test-stream` and `GET /api/storage/trash/restore/test-stream` exist for progress-stream testing. Cleanup takes an explicit `mode`: `quarantine` moves to trash and is restorable, `permanent` is not. The caller must name the mode — there is no default that silently deletes. |
 | Provider quotas and tests | `src/server/management/provider-routes.ts` — `GET /api/provider-quotas`, `POST /api/providers/test`, `GET/PUT /api/provider-context-caps`, `GET /api/provider-presets`. A quota read may be served from cache or force-refreshed; absent quota data is reported as unknown rather than as a measured zero. |
-| Models and visibility | `src/server/management/model-routes.ts` — `GET /api/models`, `PUT /api/disabled-models`, `PUT /api/model-visibility`, `PUT /api/selected-models`, `GET/POST /api/custom-models`. Visibility writes trigger catalog sync through the owning server path. |
+| Models and visibility | `src/server/management/model-routes.ts` — `GET /api/models`, `PUT /api/disabled-models`, `PUT /api/model-visibility`, `PUT /api/selected-models`, `GET/POST /api/custom-models`, `PUT /api/model-settings`. Visibility writes trigger catalog sync through the owning server path. `PUT /api/model-settings` edits one routed row's capability axes in place — context window, declared input modalities, reasoning ladder and its default — through the provider-level per-model maps the runtime already reads, so the row keeps its discovery provenance instead of being replaced by a custom model. Every field is optional and `null` clears the declaration back to the registry/catalog answer; display name is deliberately absent because `PUT /api/providers/{provider}/model-display-names` already owns it. |
 | Effort and fallback | `src/server/management/agent-settings-routes.ts` — `GET/PUT /api/effort-caps`, `/api/subagent-models`, `/api/subagent-model-fallback`. Caps clamp; they do not reject. |
 | Grok and Claude integrations | `src/server/management/agent-settings-routes.ts` — `GET /api/grok`, `PUT /api/grok/selection`, `POST /api/grok/apply`, `GET/PUT /api/claude-desktop`, `POST /api/claude-desktop/apply` (`mode`: `gateway` default for new installs, `first-party` opt-in, or legacy shapes), `GET /api/claude-desktop/status` (`mode`, `riskWarning`, `firstParty`), `GET/PUT /api/claude-code`. Gateway apply writes an external app's profile, so its status probe must read the same resolved path it writes (see [`responses.md`](transports/responses.md)); first-party apply writes only the Claude Code proxy env, see [`clients/claude-desktop.md`](clients/claude-desktop.md#desktop-modes-gateway-and-first-party). `gui/src/pages/ClaudeDesktop.tsx` renders the mode selector and sends the chosen `mode` with apply. `PUT /api/claude-code` re-runs macOS system-env reconciliation (`src/server/system-env.ts`) whenever the body carries `systemEnv`, `authMode`, a model slot or a lever field: keys opencodex tracks as injected are refreshed or unset once the config stops producing them, and a launchd value the user set before injection is never touched. |
 
diff --git a/tests/cli/cli-models-set.test.ts b/tests/cli/cli-models-set.test.ts
new file mode 100644
index 00000000000..6045f216b72
--- /dev/null
+++ b/tests/cli/cli-models-set.test.ts
@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import { handleModelsRuntimeCommand } from "../../src/cli/models-runtime";
+import { CAPABILITIES } from "../../src/cli/capabilities";
+import { MANAGEMENT_ROUTES } from "../../src/server/management/route-registry";
+
+/**
+ * `ocx models set` is the CLI half of the per-model editor. It drives the same route the
+ * dashboard does, and the tests below pin the mapping it must not blur: a clear is `null`, an
+ * explicit empty ladder is `[]`, and neither is inferred from a value that merely looks empty.
+ */
+async function invoke(args: string[], response?: unknown, status = 200) {
+  const calls: Array<{ path: string; method: string; body: unknown }> = [];
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  const log = console.log;
+  const error = console.error;
+  console.log = (...values: unknown[]) => { stdout.push(values.map(String).join(" ")); };
+  console.error = (...values: unknown[]) => { stderr.push(values.map(String).join(" ")); };
+  try {
+    const code = await handleModelsRuntimeCommand("set", args, {
+      baseUrl: "http://127.0.0.1:1",
+      fetchImpl: async (url, init) => {
+        calls.push({
+          path: new URL(String(url)).pathname,
+          method: init?.method ?? "GET",
+          body: init?.body ? JSON.parse(String(init.body)) : undefined,
+        });
+        if (response instanceof Response) return response;
+        return Response.json(response ?? { ok: true, changed: true }, { status });
+      },
+    });
+    return { code, calls, stdout: stdout.join("\n"), stderr: stderr.join("\n") };
+  } finally {
+    console.log = log;
+    console.error = error;
+  }
+}
+
+describe("models per-model settings command", () => {
+  test("each option maps to its wire field and the selector keeps the upstream id intact", async () => {
+    const result = await invoke([
+      "vendor/org/model",
+      "--context-window", "262144",
+      "--modalities", "text,image",
+      "--reasoning-efforts", "low,medium,high",
+      "--default-reasoning-effort", "medium",
+    ]);
+    expect(result.code).toBe(0);
+    expect(result.calls).toEqual([{
+      path: "/api/model-settings",
+      method: "PUT",
+      body: {
+        provider: "vendor",
+        modelId: "org/model",
+        contextWindow: 262144,
+        inputModalities: ["text", "image"],
+        reasoningEfforts: ["low", "medium", "high"],
+        defaultReasoningEffort: "medium",
+      },
+    }]);
+  });
+
+  test("every clear spelling sends null rather than a value that looks empty", async () => {
+    const result = await invoke([
+      "vendor/model",
+      "--context-window", "-",
+      "--modalities", "-",
+      "--reasoning-efforts", "-",
+      "--default-reasoning-effort", "-",
+    ]);
+    expect(result.code).toBe(0);
+    expect(result.calls[0]!.body).toEqual({
+      provider: "vendor",
+      modelId: "model",
+      contextWindow: null,
+      inputModalities: null,
+      reasoningEfforts: null,
+      defaultReasoningEffort: null,
+    });
+    // Zero is the other documented spelling for "no window override", from ocx models edit.
+    const zero = await invoke(["vendor/model", "--context-window", "0"]);
+    expect(zero.calls[0]!.body).toEqual({ provider: "vendor", modelId: "model", contextWindow: null });
+  });
+
+  test("an explicit empty ladder is [] while - restores inheritance", async () => {
+    const empty = await invoke(["vendor/model", "--reasoning-efforts", ""]);
+    expect(empty.calls[0]!.body).toEqual({ provider: "vendor", modelId: "model", reasoningEfforts: [] });
+    const inherit = await invoke(["vendor/model", "--reasoning-efforts", "-"]);
+    expect(inherit.calls[0]!.body).toEqual({ provider: "vendor", modelId: "model", reasoningEfforts: null });
+    const malformed = await invoke(["vendor/model", "--reasoning-efforts", "low,,high"]);
+    expect(malformed.code).toBe(2);
+    expect(malformed.calls).toEqual([]);
+  });
+
+  test("--reset clears every axis at once and refuses to be combined", async () => {
+    const reset = await invoke(["vendor/model", "--reset"]);
+    expect(reset.code).toBe(0);
+    expect(reset.calls[0]!.body).toEqual({
+      provider: "vendor",
+      modelId: "model",
+      contextWindow: null,
+      inputModalities: null,
+      reasoningEfforts: null,
+      defaultReasoningEffort: null,
+    });
+    const combined = await invoke(["vendor/model", "--reset", "--modalities", "text"]);
+    expect(combined.code).toBe(2);
+    expect(combined.calls).toEqual([]);
+  });
+
+  test("a request with nothing to change, or a native selector, never reaches the API", async () => {
+    const empty = await invoke(["vendor/model"]);
+    expect(empty.code).toBe(2);
+    expect(empty.calls).toEqual([]);
+    const native = await invoke(["gpt-5.6-luna", "--modalities", "text"]);
+    expect(native.code).toBe(2);
+    expect(native.stderr).toContain("routed model");
+    expect(native.calls).toEqual([]);
+    const invalidWindow = await invoke(["vendor/model", "--context-window", "12k"]);
+    expect(invalidWindow.code).toBe(2);
+    expect(invalidWindow.calls).toEqual([]);
+  });
+
+  test("an unchanged answer says so instead of claiming a write", async () => {
+    const result = await invoke(["vendor/model", "--reset"], { ok: true, changed: false });
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain("no overrides");
+  });
+
+  test("the capability declares the route this verb drives", () => {
+    const capability = CAPABILITIES.find(entry => entry.command.join(" ") === "models set");
+    expect(capability?.routes).toEqual([{ method: "PUT", path: "/api/model-settings" }]);
+    expect(capability?.mutates).toBe(true);
+    expect(MANAGEMENT_ROUTES.some(route => route.method === "PUT" && route.path === "/api/model-settings")).toBe(true);
+  });
+});
diff --git a/tests/codex-integration/codex-convergence-contract.test.ts b/tests/codex-integration/codex-convergence-contract.test.ts
index 96445231635..6de98e7ab06 100644
--- a/tests/codex-integration/codex-convergence-contract.test.ts
+++ b/tests/codex-integration/codex-convergence-contract.test.ts
@@ -374,10 +374,10 @@ test("a failure cause never carries message text, paths or identifiers (#1784)",
   expect(body).not.toContain("failed writing");
 });
 
-test("the route inventory contains exactly the specified 8 + 14 + 2 + 2 convergence paths", () => {
+test("the route inventory contains exactly the specified 8 + 15 + 2 + 2 convergence paths", () => {
   const counts = Object.fromEntries([
     ["provider-routes.ts", 8],
-    ["model-routes.ts", 14],
+    ["model-routes.ts", 15],
     ["combo-routes.ts", 2],
     ["agent-settings-routes.ts", 2],
   ].map(([file, expected]) => {
@@ -396,7 +396,7 @@ test("the route inventory contains exactly the specified 8 + 14 + 2 + 2 converge
   }));
   expect(counts).toEqual({
     "provider-routes.ts": 8,
-    "model-routes.ts": 14,
+    "model-routes.ts": 15,
     "combo-routes.ts": 2,
     "agent-settings-routes.ts": 2,
   });
@@ -447,6 +447,31 @@ test("both model-preset write paths converge the Codex catalog", () => {
   expect(customBranch).not.toMatch(/await converge(?:CodexCatalog|VisibleCatalogs)\(\)/);
 });
 
+/**
+ * The fifteenth model-route call belongs to `PUT /api/model-settings`: it writes the per-model
+ * context window, declared input modalities and reasoning ladder the catalog publishes for that
+ * row, so the exported catalog is stale the moment the config is saved. Keep this route-specific
+ * assertion beside the total for the same reason the preset pair above has one — otherwise a
+ * later bump could satisfy the count while this route quietly lost its own convergence.
+ */
+test("the per-model settings route converges the Codex catalog once", () => {
+  const source = readFileSync(
+    repoPath("src", "server", "management", "model-routes.ts"),
+    "utf8",
+  );
+  const handlerStart = source.indexOf('url.pathname === "/api/model-settings" && req.method === "PUT"');
+  expect(handlerStart).toBeGreaterThan(-1);
+  // Sliced to the next route check, as above: a fixed far boundary would swallow a later
+  // route's convergence call and count it as this one's.
+  const handlerBody = source.slice(handlerStart, source.indexOf("url.pathname ===", handlerStart + 1));
+  expect(handlerBody.match(/await convergeCodexCatalog\(\)/g)?.length).toBe(1);
+  // An unchanged request must not converge: `changed: false` is the no-op answer, and the
+  // convergence sits behind it rather than before the early return.
+  const earlyReturn = handlerBody.indexOf("if (!changed) return jsonResponse");
+  expect(earlyReturn).toBeGreaterThan(-1);
+  expect(handlerBody.indexOf("await convergeCodexCatalog()")).toBeGreaterThan(earlyReturn);
+});
+
 /**
  * The inventory above is a bare count, so raising it is the obvious way to make this file
  * green again — and a count that only ever gets raised stops being a contract. #1541's
diff --git a/tests/fixtures/test-layout-expected.json b/tests/fixtures/test-layout-expected.json
index 2924eaf5ca9..c075e203757 100644
--- a/tests/fixtures/test-layout-expected.json
+++ b/tests/fixtures/test-layout-expected.json
@@ -375,7 +375,7 @@
   "cli-models-free-only.test.ts": "cli",
   "cli-models-price.test.ts": "cli",
   "cli-models-reasoning.test.ts": "cli",
-  "cli-models-runtime-dispatch.test.ts": "cli",
+  "cli-models-runtime-dispatch.test.ts": "cli", "cli-models-set.test.ts": "cli",
   "cli-models.test.ts": "cli",
   "cli-native-profile.test.ts": "cli",
   "cli-observe-logs.test.ts": "cli",
@@ -1082,7 +1082,7 @@
   "model-pinned-effort.test.ts": "codex-integration",
   "model-presets.test.ts": "providers",
   "model-rename-migration.test.ts": "providers",
-  "model-selection-guidance.test.ts": "cli",
+  "model-selection-guidance.test.ts": "cli", "model-settings-management-api.test.ts": "server",
   "model-visibility-management-api.test.ts": "codex-integration",
   "models-feedback-callback.test.ts": "gui",
   "models-free-filter.test.ts": "gui",
diff --git a/tests/server/model-settings-management-api.test.ts b/tests/server/model-settings-management-api.test.ts
new file mode 100644
index 00000000000..f00b5207f1e
--- /dev/null
+++ b/tests/server/model-settings-management-api.test.ts
@@ -0,0 +1,364 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { clearModelCache, getFreshCached, setCached } from "../../src/codex/model-cache";
+import { resetCodexModelEntitlementCacheForTests } from "../../src/codex/model-entitlements";
+import { handleModelRoutes } from "../../src/server/management/model-routes";
+import { listManagementModelRows } from "../../src/server/management/model-rows";
+import type { CatalogModel } from "../../src/codex/catalog";
+import type { OcxConfig } from "../../src/types";
+import { removeTreeWithRetry } from "../helpers/remove-tree";
+
+/**
+ * `PUT /api/model-settings` writes per-model overrides onto a routed row.
+ *
+ * The tests below pin the two properties the dashboard depends on and that are easy to lose:
+ * only the axes the caller sent are written (an omitted field must not be pinned as an override),
+ * and `null` clears rather than defaulting. Everything else here is the ingress validation that
+ * keeps a rejected value out of a config the catalog then has to special-case.
+ */
+const PROVIDER = "model-settings-test";
+const MODEL = "vendor/model";
+
+let home: string;
+let previousHome: string | undefined;
+let previousCodexHome: string | undefined;
+
+function fixture(): OcxConfig {
+  return {
+    port: 10100,
+    defaultProvider: PROVIDER,
+    modelCacheTtlMs: 60_000,
+    providers: {
+      [PROVIDER]: {
+        adapter: "openai-chat",
+        baseUrl: "https://settings.example.invalid/v1",
+        liveModels: false,
+        models: [MODEL, "vendor/other"],
+      },
+      openai: { adapter: "openai-responses", baseUrl: "https://api.openai.invalid/v1", models: ["gpt-5.6-luna"] },
+      // The combo namespace is reserved, so a provider literally named "combo" is not something a
+      // user configures. It is here to exercise the guard: the route refuses it by name.
+      combo: { adapter: "openai-chat", baseUrl: "https://combo.invalid/v1", models: [] },
+    },
+  };
+}
+
+beforeEach(() => {
+  previousHome = process.env.OPENCODEX_HOME;
+  previousCodexHome = process.env.CODEX_HOME;
+  home = mkdtempSync(join(tmpdir(), "ocx-model-settings-"));
+  process.env.OPENCODEX_HOME = home;
+  process.env.CODEX_HOME = join(home, "codex");
+});
+
+afterEach(() => {
+  clearModelCache();
+  resetCodexModelEntitlementCacheForTests();
+  if (previousHome === undefined) delete process.env.OPENCODEX_HOME;
+  else process.env.OPENCODEX_HOME = previousHome;
+  if (previousCodexHome === undefined) delete process.env.CODEX_HOME;
+  else process.env.CODEX_HOME = previousCodexHome;
+  removeTreeWithRetry(home);
+});
+
+function harness(config = fixture(), converge?: () => Promise<never>) {
+  const persisted: OcxConfig[] = [];
+  let convergeCalls = 0;
+  async function call(body?: unknown, rawBody?: string) {
+    const url = new URL("http://127.0.0.1:10100/api/model-settings");
+    const response = await handleModelRoutes({
+      version: "test",
+      req: new Request(url, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: rawBody ?? JSON.stringify(body),
+      }),
+      url,
+      config,
+      deps: {
+        saveConfigPreservingClaudeCode: saved => { persisted.push(structuredClone(saved)); },
+      },
+      convergeCodexCatalog: async () => {
+        convergeCalls += 1;
+        if (converge) return converge();
+        return { status: "ok", changed: true } as never;
+      },
+      syncClaudeAgentDefsBestEffort: async () => {},
+    });
+    if (!response) throw new Error("model-settings route was not dispatched");
+    return response;
+  }
+  return { call, config, persisted, get convergeCalls() { return convergeCalls; } };
+}
+
+describe("per-model settings API", () => {
+  test("each axis round-trips, persists once, and converges the catalog once", async () => {
+    const h = harness();
+    const response = await h.call({
+      provider: PROVIDER,
+      modelId: MODEL,
+      contextWindow: 262_144,
+      inputModalities: ["text", "image"],
+      reasoningEfforts: ["low", "medium", "high"],
+      defaultReasoningEffort: "medium",
+    });
+    expect(response.status).toBe(200);
+    expect(await response.json()).toMatchObject({
+      ok: true,
+      provider: PROVIDER,
+      modelId: MODEL,
+      contextWindow: 262_144,
+      inputModalities: ["text", "image"],
+      reasoningEfforts: ["low", "medium", "high"],
+      defaultReasoningEffort: "medium",
+      changed: true,
+    });
+    const provider = h.config.providers[PROVIDER]!;
+    expect(provider.modelContextWindows).toEqual({ [MODEL]: 262_144 });
+    expect(provider.modelCapabilities).toEqual({ [MODEL]: { inputModalities: ["text", "image"] } });
+    expect(provider.modelReasoningEfforts).toEqual({ [MODEL]: ["low", "medium", "high"] });
+    expect(provider.modelDefaultReasoningEfforts).toEqual({ [MODEL]: "medium" });
+    expect(h.persisted).toHaveLength(1);
+    expect(h.convergeCalls).toBe(1);
+  });
+
+  /*
+   * The gather bakes resolved hints into the rows it caches, and a cache hit re-applies the config
+   * through `clampObservedModelLimits`, where a configured window may only lower the observed one.
+   * Without this clear, raising or clearing an override keeps reading back the previous answer for
+   * the whole TTL — so the clear is part of the write, not an optimisation.
+   */
+  test("a real write drops the provider's discovery cache before converging", async () => {
+    setCached(PROVIDER, [{ provider: PROVIDER, id: MODEL, contextWindow: 65_536 }]);
+    let cacheWasClearAtConvergence = false;
+    const h = harness(fixture(), async () => {
+      cacheWasClearAtConvergence = getFreshCached(PROVIDER, 60_000) === null;
+      return { status: "ok", changed: true } as never;
+    });
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, contextWindow: 200_000 });
+
+    expect(response.status).toBe(200);
+    expect(cacheWasClearAtConvergence).toBe(true);
+  });
+
+  test("a no-op request leaves the cache alone and never converges", async () => {
+    setCached(PROVIDER, [{ provider: PROVIDER, id: MODEL }]);
+    const h = harness();
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL });
+
+    expect(await response.json()).toMatchObject({ changed: false });
+    expect(getFreshCached(PROVIDER, 60_000)).not.toBeNull();
+    expect(h.convergeCalls).toBe(0);
+  });
+
+  test("an omitted axis is left alone rather than pinned", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelContextWindows = { [MODEL]: 131_072 };
+    await h.call({ provider: PROVIDER, modelId: MODEL, inputModalities: ["text"] });
+    const provider = h.config.providers[PROVIDER]!;
+    expect(provider.modelContextWindows).toEqual({ [MODEL]: 131_072 });
+    expect(provider.modelReasoningEfforts).toBeUndefined();
+    expect(provider.modelDefaultReasoningEfforts).toBeUndefined();
+  });
+
+  test("null clears, an emptied map is removed, and a repeated clear reports changed:false", async () => {
+    const h = harness();
+    await h.call({ provider: PROVIDER, modelId: MODEL, contextWindow: 200_000, inputModalities: ["text"] });
+    const cleared = await h.call({
+      provider: PROVIDER,
+      modelId: MODEL,
+      contextWindow: null,
+      inputModalities: null,
+      reasoningEfforts: null,
+      defaultReasoningEffort: null,
+    });
+    expect(await cleared.json()).toMatchObject({ changed: true, contextWindow: null, inputModalities: null });
+    const provider = h.config.providers[PROVIDER]!;
+    expect(provider.modelContextWindows).toBeUndefined();
+    expect(provider.modelCapabilities).toBeUndefined();
+    expect(provider.modelReasoningEfforts).toBeUndefined();
+    expect(provider.modelDefaultReasoningEfforts).toBeUndefined();
+    // The second identical request must not claim it restored anything: the dashboard says
+    // "already the computed values" on this answer instead of reporting a restore.
+    const again = await h.call({ provider: PROVIDER, modelId: MODEL, contextWindow: null, inputModalities: null });
+    expect(await again.json()).toMatchObject({ changed: false });
+    // The set and the clear each changed something; the repeated clear changed nothing.
+    expect(h.persisted).toHaveLength(2);
+    expect(h.convergeCalls).toBe(2);
+  });
+
+  test("an empty modality array clears the declaration instead of storing a text-only model", async () => {
+    const h = harness();
+    await h.call({ provider: PROVIDER, modelId: MODEL, inputModalities: ["text", "image"] });
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, inputModalities: [] });
+    expect(await response.json()).toMatchObject({ inputModalities: null });
+    expect(h.config.providers[PROVIDER]!.modelCapabilities).toBeUndefined();
+  });
+
+  test("an explicit empty ladder is stored as the no-reasoning override", async () => {
+    const h = harness();
+    await h.call({ provider: PROVIDER, modelId: MODEL, reasoningEfforts: [] });
+    expect(h.config.providers[PROVIDER]!.modelReasoningEfforts).toEqual({ [MODEL]: [] });
+  });
+
+  test("ingress validation rejects what the catalog could not represent", async () => {
+    const h = harness();
+    const cases: [unknown, string][] = [
+      [{ provider: PROVIDER, modelId: MODEL, inputModalities: ["video"] }, "unsupported input modality"],
+      [{ provider: PROVIDER, modelId: MODEL, contextWindow: -1 }, "contextWindow must be a positive number"],
+      [{ provider: PROVIDER, modelId: MODEL, reasoningEfforts: ["low"], defaultReasoningEffort: "max" }, "not in the declared reasoningEfforts ladder"],
+      [{ provider: PROVIDER, modelId: MODEL, reasoningEfforts: ["turbo"] }, "unsupported reasoning effort"],
+      [{ provider: PROVIDER }, "provider and modelId are required"],
+      [{ provider: "nope", modelId: MODEL }, "unknown model settings provider"],
+      [{ provider: "openai", modelId: "gpt-5.6-luna" }, "only available for routed providers"],
+      [{ provider: "combo", modelId: MODEL }, "only available for routed providers"],
+    ];
+    for (const [body, expected] of cases) {
+      const response = await h.call(body);
+      expect(response.status).toBe(400);
+      expect(String((await response.json() as { error?: string }).error)).toContain(expected);
+    }
+    expect(h.persisted).toHaveLength(0);
+    expect(h.convergeCalls).toBe(0);
+  });
+
+  test("a malformed body is a 400, not a crash", async () => {
+    const h = harness();
+    expect((await h.call(undefined, "{")).status).toBe(400);
+    expect((await h.call(["nope"])).status).toBe(400);
+    expect(h.persisted).toHaveLength(0);
+  });
+
+  test("the row projection reports the declaration and the reasoning verdict, not the catalog value", async () => {
+    const h = harness();
+    const roster: CatalogModel[] = [{
+      id: MODEL,
+      provider: PROVIDER,
+      // What the provider published. The declaration below is what the operator stored, and the
+      // two must stay distinguishable or an editor cannot round-trip its own writes.
+      inputModalities: ["text", "image"],
+    }];
+    // Match on provider + upstream id: the Codex-facing slug escapes the model's own slash
+    // (slug-codec), so the namespaced form is not provider + "/" + modelId.
+    const rowOf = async () => (await listManagementModelRows(h.config, { models: roster, entitlementWaitMs: 0 }))
+      .find(row => row.provider === PROVIDER && row.id === MODEL)!;
+    const before = await rowOf();
+    expect(before.inputModalitiesDeclared).toBeUndefined();
+    expect(before.reasoningOverridden).toBe(false);
+
+    await h.call({ provider: PROVIDER, modelId: MODEL, inputModalities: ["text"], reasoningEfforts: ["low"] });
+    const after = await rowOf();
+    expect(after.inputModalitiesDeclared).toEqual(["text"]);
+    expect(after.inputModalities).toEqual(["text", "image"]);
+    expect(after.reasoningEfforts).toEqual(["low"]);
+    expect(after.reasoningOverridden).toBe(true);
+  });
+
+  /*
+   * "No rungs" is a declaration, not an absence. Reading an empty stored ladder as "inherit"
+   * hands the editor a ladder the row does not have, and the next save persists it as the
+   * operator's own edit — the exact drift this surface exists to prevent.
+   */
+  test("an explicit empty ladder survives the projection instead of inheriting one", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelReasoningEfforts = { [MODEL]: [] };
+    const row = (await listManagementModelRows(h.config, {
+      models: [{ id: MODEL, provider: PROVIDER }],
+      entitlementWaitMs: 0,
+    })).find(candidate => candidate.provider === PROVIDER && candidate.id === MODEL)!;
+
+    expect(row.reasoningEfforts).toEqual([]);
+    expect(row.reasoningOverridden).toBe(true);
+  });
+
+  /*
+   * A ladder write can strand a stored default the model can no longer select. The caller said
+   * nothing about the default, so only one that cannot survive the new ladder is cleared.
+   */
+  test("a shrunk ladder clears a stored default it can no longer select", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelReasoningEfforts = { [MODEL]: ["low", "medium", "high"] };
+    h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts = { [MODEL]: "high" };
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, reasoningEfforts: ["low"] });
+
+    expect(response.status).toBe(200);
+    expect(h.config.providers[PROVIDER]!.modelReasoningEfforts).toEqual({ [MODEL]: ["low"] });
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toBeUndefined();
+  });
+
+  test("a default that survives the new ladder is left alone", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelReasoningEfforts = { [MODEL]: ["low", "medium"] };
+    h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts = { [MODEL]: "medium" };
+
+    await h.call({ provider: PROVIDER, modelId: MODEL, reasoningEfforts: ["low", "medium", "high"] });
+
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toEqual({ [MODEL]: "medium" });
+  });
+
+  test("clearing the ladder clears a default nothing inherits any more", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelReasoningEfforts = { [MODEL]: ["low", "high"] };
+    h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts = { [MODEL]: "high" };
+
+    await h.call({ provider: PROVIDER, modelId: MODEL, reasoningEfforts: null });
+
+    expect(h.config.providers[PROVIDER]!.modelReasoningEfforts).toBeUndefined();
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toBeUndefined();
+  });
+
+  /*
+   * A default-only request has no ladder in the body, so it must be judged against the ladder the
+   * model actually resolves — a per-model entry is only one of four sources, and rejecting the
+   * provider-level one would refuse a level the model really offers.
+   */
+  test("a default-only write is judged against the ladder the model inherits", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.reasoningEfforts = ["low", "medium", "high"];
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, defaultReasoningEffort: "high" });
+
+    expect(response.status).toBe(200);
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toEqual({ [MODEL]: "high" });
+    expect(h.config.providers[PROVIDER]!.modelReasoningEfforts).toBeUndefined();
+  });
+
+  test("a default outside the inherited ladder is still refused", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.reasoningEfforts = ["low", "medium"];
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, defaultReasoningEffort: "max" });
+
+    expect(response.status).toBe(400);
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toBeUndefined();
+  });
+
+  test("clearing the per-model ladder judges the default against the inherited one", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.reasoningEfforts = ["low", "high"];
+    h.config.providers[PROVIDER]!.modelReasoningEfforts = { [MODEL]: ["low", "medium", "high"] };
+
+    const response = await h.call({
+      provider: PROVIDER, modelId: MODEL, reasoningEfforts: null, defaultReasoningEffort: "high",
+    });
+
+    expect(response.status).toBe(200);
+    expect(h.config.providers[PROVIDER]!.modelReasoningEfforts).toBeUndefined();
+    expect(h.config.providers[PROVIDER]!.modelDefaultReasoningEfforts).toEqual({ [MODEL]: "high" });
+  });
+
+  test("duplicate modalities are deduplicated before the unchanged check", async () => {
+    const h = harness();
+    h.config.providers[PROVIDER]!.modelCapabilities = { [MODEL]: { inputModalities: ["text", "image"] } };
+
+    const response = await h.call({ provider: PROVIDER, modelId: MODEL, inputModalities: ["text", "text"] });
+
+    expect(await response.json()).toMatchObject({ changed: true, inputModalities: ["text"] });
+    expect(h.config.providers[PROVIDER]!.modelCapabilities).toEqual({ [MODEL]: { inputModalities: ["text"] } });
+  });
+});