fix(cli): keep json preflight stdout machine-readable

src/cli/program/config-guard.test.ts

@@ -34,10 +34,10 @@ describe("ensureConfigReady", () => {
     return await import("./config-guard.js");
   }
 
-  async function runEnsureConfigReady(commandPath: string[]) {
+  async function runEnsureConfigReady(commandPath: string[], suppressDoctorStdout = false) {
     const runtime = makeRuntime();
     const { ensureConfigReady } = await loadEnsureConfigReady();
-    await ensureConfigReady({ runtime: runtime as never, commandPath });
+    await ensureConfigReady({ runtime: runtime as never, commandPath, suppressDoctorStdout });
     return runtime;
   }
 
@@ -100,4 +100,43 @@ describe("ensureConfigReady", () => {
 
     expect(loadAndMaybeMigrateDoctorConfigMock).toHaveBeenCalledTimes(1);
   });
+
+  it("still runs doctor flow when stdout suppression is enabled", async () => {
+    await runEnsureConfigReady(["message"], true);
+    expect(loadAndMaybeMigrateDoctorConfigMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("prevents preflight stdout noise when suppression is enabled", async () => {
+    const stdoutWrites: string[] = [];
+    const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(((chunk: unknown) => {
+      stdoutWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write);
+    loadAndMaybeMigrateDoctorConfigMock.mockImplementation(async () => {
+      process.stdout.write("Doctor warnings\n");
+    });
+    try {
+      await runEnsureConfigReady(["message"], true);
+      expect(stdoutWrites.join("")).not.toContain("Doctor warnings");
+    } finally {
+      writeSpy.mockRestore();
+    }
+  });
+
+  it("allows preflight stdout noise when suppression is not enabled", async () => {
+    const stdoutWrites: string[] = [];
+    const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(((chunk: unknown) => {
+      stdoutWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write);
+    loadAndMaybeMigrateDoctorConfigMock.mockImplementation(async () => {
+      process.stdout.write("Doctor warnings\n");
+    });
+    try {
+      await runEnsureConfigReady(["message"], false);
+      expect(stdoutWrites.join("")).toContain("Doctor warnings");
+    } finally {
+      writeSpy.mockRestore();
+    }
+  });
 });

src/cli/program/config-guard.ts

@@ -39,14 +39,27 @@ async function getConfigSnapshot() {
 export async function ensureConfigReady(params: {
   runtime: RuntimeEnv;
   commandPath?: string[];
+  suppressDoctorStdout?: boolean;
 }): Promise<void> {
   const commandPath = params.commandPath ?? [];
   if (!didRunDoctorConfigFlow && shouldMigrateStateFromPath(commandPath)) {
     didRunDoctorConfigFlow = true;
-    await loadAndMaybeMigrateDoctorConfig({
-      options: { nonInteractive: true },
-      confirm: async () => false,
-    });
+    const runDoctorConfigFlow = async () =>
+      loadAndMaybeMigrateDoctorConfig({
+        options: { nonInteractive: true },
+        confirm: async () => false,
+      });
+    if (!params.suppressDoctorStdout) {
+      await runDoctorConfigFlow();
+    } else {
+      const originalStdoutWrite = process.stdout.write;
+      process.stdout.write = ((() => true) as unknown) as typeof process.stdout.write;
+      try {
+        await runDoctorConfigFlow();
+      } finally {
+        process.stdout.write = originalStdoutWrite;
+      }
+    }
   }
 
   const snapshot = await getConfigSnapshot();

src/cli/program/preaction.test.ts

@@ -78,7 +78,18 @@ describe("registerPreActionHooks", () => {
     program.command("doctor").action(async () => {});
     program.command("completion").action(async () => {});
     program.command("secrets").action(async () => {});
-    program.command("update").action(async () => {});
+    program
+      .command("update")
+      .command("status")
+      .option("--json")
+      .action(async () => {});
+    const config = program.command("config");
+    config
+      .command("set")
+      .argument("<path>")
+      .argument("<value>")
+      .option("--json")
+      .action(async () => {});
     program.command("channels").action(async () => {});
     program.command("directory").action(async () => {});
     program.command("agents").action(async () => {});
@@ -87,6 +98,7 @@ describe("registerPreActionHooks", () => {
     program
       .command("message")
       .command("send")
+      .option("--json")
       .action(async () => {});
     registerPreActionHooks(program, "9.9.9-test");
     return program;
@@ -194,4 +206,46 @@ describe("registerPreActionHooks", () => {
     expect(emitCliBannerMock).not.toHaveBeenCalled();
     expect(ensureConfigReadyMock).toHaveBeenCalledTimes(1);
   });
+
+  it("suppresses doctor stdout for any --json output command", async () => {
+    await runCommand({
+      parseArgv: ["message", "send", "--json"],
+      processArgv: ["node", "openclaw", "message", "send", "--json"],
+    });
+
+    expect(ensureConfigReadyMock).toHaveBeenCalledWith({
+      runtime: runtimeMock,
+      commandPath: ["message", "send"],
+      suppressDoctorStdout: true,
+    });
+
+    vi.clearAllMocks();
+
+    await runCommand({
+      parseArgv: ["update", "status", "--json"],
+      processArgv: ["node", "openclaw", "update", "status", "--json"],
+    });
+
+    expect(ensureConfigReadyMock).toHaveBeenCalledWith({
+      runtime: runtimeMock,
+      commandPath: ["update", "status"],
+      suppressDoctorStdout: true,
+    });
+  });
+
+  it("does not treat config set --json (strict-parse alias) as json output mode", async () => {
+    await runCommand({
+      parseArgv: ["config", "set", "gateway.auth.mode", "{bad", "--json"],
+      processArgv: ["node", "openclaw", "config", "set", "gateway.auth.mode", "{bad", "--json"],
+    });
+
+    const firstCall = ensureConfigReadyMock.mock.calls[0]?.[0] as
+      | { suppressDoctorStdout?: boolean }
+      | undefined;
+    expect(firstCall?.suppressDoctorStdout).toBeUndefined();
+    expect(ensureConfigReadyMock).toHaveBeenCalledWith({
+      runtime: runtimeMock,
+      commandPath: ["config", "set"],
+    });
+  });
 });

src/cli/program/preaction.ts

@@ -3,7 +3,7 @@ import { setVerbose } from "../../globals.js";
 import { isTruthyEnvValue } from "../../infra/env.js";
 import type { LogLevel } from "../../logging/levels.js";
 import { defaultRuntime } from "../../runtime.js";
-import { getCommandPath, getVerboseFlag, hasHelpOrVersion } from "../argv.js";
+import { getCommandPath, getVerboseFlag, hasFlag, hasHelpOrVersion } from "../argv.js";
 import { emitCliBanner } from "../banner.js";
 import { resolveCliName } from "../cli-name.js";
 
@@ -30,6 +30,7 @@ const PLUGIN_REQUIRED_COMMANDS = new Set([
   "onboard",
 ]);
 const CONFIG_GUARD_BYPASS_COMMANDS = new Set(["doctor", "completion", "secrets"]);
+const JSON_PARSE_ONLY_COMMANDS = new Set(["config set"]);
 
 function getRootCommand(command: Command): Command {
   let current = command;
@@ -51,6 +52,17 @@ function getCliLogLevel(actionCommand: Command): LogLevel | undefined {
   return typeof logLevel === "string" ? (logLevel as LogLevel) : undefined;
 }
 
+function isJsonOutputMode(commandPath: string[], argv: string[]): boolean {
+  if (!hasFlag(argv, "--json")) {
+    return false;
+  }
+  const key = `${commandPath[0] ?? ""} ${commandPath[1] ?? ""}`.trim();
+  if (JSON_PARSE_ONLY_COMMANDS.has(key)) {
+    return false;
+  }
+  return true;
+}
+
 export function registerPreActionHooks(program: Command, programVersion: string) {
   program.hook("preAction", async (_thisCommand, actionCommand) => {
     setProcessTitleForCommand(actionCommand);
@@ -79,8 +91,13 @@ export function registerPreActionHooks(program: Command, programVersion: string)
     if (CONFIG_GUARD_BYPASS_COMMANDS.has(commandPath[0])) {
       return;
     }
+    const suppressDoctorStdout = isJsonOutputMode(commandPath, argv);
     const { ensureConfigReady } = await import("./config-guard.js");
-    await ensureConfigReady({ runtime: defaultRuntime, commandPath });
+    await ensureConfigReady({
+      runtime: defaultRuntime,
+      commandPath,
+      ...(suppressDoctorStdout ? { suppressDoctorStdout: true } : {}),
+    });
     // Load plugins for commands that need channel access
     if (PLUGIN_REQUIRED_COMMANDS.has(commandPath[0])) {
       const { ensurePluginRegistryLoaded } = await import("../plugin-registry.js");