fix: reject agent-scoped model default writes

src/cli/models-cli.test.ts

@@ -5,6 +5,8 @@ import { registerModelsCli } from "./models-cli.js";
 
 const mocks = vi.hoisted(() => ({
   modelsStatusCommand: vi.fn().mockResolvedValue(undefined),
+  modelsSetCommand: vi.fn().mockResolvedValue(undefined),
+  modelsSetImageCommand: vi.fn().mockResolvedValue(undefined),
   noopAsync: vi.fn(async () => undefined),
   modelsAuthAddCommand: vi.fn().mockResolvedValue(undefined),
   modelsAuthLoginCommand: vi.fn().mockResolvedValue(undefined),
@@ -17,6 +19,8 @@ const {
   modelsAuthLoginCommand,
   modelsAuthPasteTokenCommand,
   modelsAuthSetupTokenCommand,
+  modelsSetCommand,
+  modelsSetImageCommand,
   modelsStatusCommand,
 } = mocks;
 
@@ -58,10 +62,10 @@ vi.mock("../commands/models/scan.js", () => ({
   modelsScanCommand: mocks.noopAsync,
 }));
 vi.mock("../commands/models/set.js", () => ({
-  modelsSetCommand: mocks.noopAsync,
+  modelsSetCommand: mocks.modelsSetCommand,
 }));
 vi.mock("../commands/models/set-image.js", () => ({
-  modelsSetImageCommand: mocks.noopAsync,
+  modelsSetImageCommand: mocks.modelsSetImageCommand,
 }));
 
 describe("models cli", () => {
@@ -70,6 +74,8 @@ describe("models cli", () => {
     modelsAuthLoginCommand.mockClear();
     modelsAuthPasteTokenCommand.mockClear();
     modelsAuthSetupTokenCommand.mockClear();
+    modelsSetCommand.mockClear();
+    modelsSetImageCommand.mockClear();
     modelsStatusCommand.mockClear();
   });
 
@@ -162,6 +168,23 @@ describe("models cli", () => {
     expect(command).toHaveBeenCalledWith(expect.objectContaining(expected), expect.any(Object));
   });
 
+  it.each([
+    {
+      label: "set",
+      args: ["models", "--agent", "poe", "set", "anthropic/claude-sonnet-4-6"],
+      command: modelsSetCommand,
+    },
+    {
+      label: "set-image",
+      args: ["models", "--agent", "poe", "set-image", "openai/gpt-image-1"],
+      command: modelsSetImageCommand,
+    },
+  ])("rejects parent --agent for models $label", async ({ args, command }) => {
+    await expect(runModelsCommand(args)).rejects.toThrow("does not support `--agent`");
+
+    expect(command).not.toHaveBeenCalled();
+  });
+
   it("shows help for models auth without error exit", async () => {
     const program = new Command();
     program.exitOverride();

src/cli/models-cli.ts

@@ -8,6 +8,16 @@ function runModelsCommand(action: () => Promise<void>) {
   return runCommandWithRuntime(defaultRuntime, action);
 }
 
+function rejectAgentScopedModelWrite(command: Command, commandName: "set" | "set-image"): void {
+  const agent = resolveOptionFromCommand<string>(command, "agent");
+  if (!agent) {
+    return;
+  }
+  throw new Error(
+    `\`openclaw models ${commandName}\` does not support \`--agent\`; it only updates global model defaults. Remove \`--agent\` or use agent config to set a per-agent model override.`,
+  );
+}
+
 export function registerModelsCli(program: Command) {
   const models = program
     .command("models")
@@ -94,7 +104,8 @@ export function registerModelsCli(program: Command) {
     .command("set")
     .description("Set the default model")
     .argument("<model>", "Model id or alias")
-    .action(async (model: string) => {
+    .action(async (model: string, _opts: unknown, command: Command) => {
+      rejectAgentScopedModelWrite(command, "set");
       await runModelsCommand(async () => {
         const { modelsSetCommand } = await import("../commands/models/set.js");
         await modelsSetCommand(model, defaultRuntime);
@@ -105,7 +116,8 @@ export function registerModelsCli(program: Command) {
     .command("set-image")
     .description("Set the image model")
     .argument("<model>", "Model id or alias")
-    .action(async (model: string) => {
+    .action(async (model: string, _opts: unknown, command: Command) => {
+      rejectAgentScopedModelWrite(command, "set-image");
       await runModelsCommand(async () => {
         const { modelsSetImageCommand } = await import("../commands/models/set-image.js");
         await modelsSetImageCommand(model, defaultRuntime);