- State integrity and permissions checks (sessions, transcripts, state dir).

- Config file permission checks (chmod 600) when running locally.

- Model auth health: checks OAuth expiry, can refresh expiring tokens, and reports auth-profile cooldown/disabled states.

- Extra workspace dir detection (`~/openclaw`).

</Accordion>

<Accordion title="Gateway, services, and supervisors">

- Sandbox image repair when sandboxing is enabled.

<Accordion title="10. systemd linger (Linux)">

If running as a systemd user service, doctor ensures lingering is enabled so the gateway stays alive after logout.

</Accordion>

<Accordion title="11. Workspace status (skills, plugins, and legacy dirs)">

<Accordion title="11. Workspace status (skills, plugins, and TaskFlows)">

Doctor prints a summary of the workspace state for the default agent:

- **Skills status**: counts eligible, missing-requirements, and allowlist-blocked skills.

- **Legacy workspace dirs**: warns when `~/openclaw` or other legacy workspace directories exist alongside the current workspace.

- **Plugin status**: counts enabled/disabled/errored plugins; lists plugin IDs for any errors; reports bundle plugin capabilities.

- **Plugin compatibility warnings**: flags plugins that have compatibility issues with the current runtime.

- **Plugin diagnostics**: surfaces any load-time warnings or errors emitted by the plugin registry.

- **TaskFlow recovery**: surfaces suspicious managed TaskFlows that need manual inspection or cancellation.

</Accordion>

<Accordion title="11b. Bootstrap file size">

import path from "node:path";

import { beforeEach, describe, expect, it, vi } from "vitest";

import type { OpenClawConfig } from "../config/config.js";

import type { checkQmdBinaryAvailability as checkQmdBinaryAvailabilityFn } from "../memory-host-sdk/engine-qmd.js";

import { noteMemorySearchHealth } from "./doctor-memory-search.js";

import { maybeRepairMemoryRecallHealth, noteMemoryRecallHealth } from "./doctor-memory-search.js";

import { detectLegacyWorkspaceDirs, formatRootMemoryFilesWarning } from "./doctor-workspace.js";

import { formatRootMemoryFilesWarning } from "./doctor-workspace.js";

function resetMemoryRecallMocks() {

auditShortTermPromotionArtifacts.mockReset();

});

});

describe("detectLegacyWorkspaceDirs", () => {

it("returns active workspace and no legacy dirs", () => {

const workspaceDir = "/home/user/openclaw";

const detection = detectLegacyWorkspaceDirs({ workspaceDir });

expect(detection.activeWorkspace).toBe(path.resolve(workspaceDir));

expect(detection.legacyDirs).toStrictEqual([]);

});

});

describe("formatRootMemoryFilesWarning", () => {

it("explains split-brain when both root memory files exist", () => {

const message = formatRootMemoryFilesWarning({

import { buildWorkspaceSkillStatus } from "../skills/discovery/status.js";

import { listTasksForFlowId } from "../tasks/runtime-internal.js";

import { listTaskFlowRecords } from "../tasks/task-flow-runtime-internal.js";

import { detectLegacyWorkspaceDirs, formatLegacyWorkspaceWarning } from "./doctor-workspace.js";

type NoteWorkspaceStatusOptions = {

pluginVersionDrift?: PluginVersionDriftReport;

/** Emits workspace, skills, plugin, and TaskFlow recovery status notes for doctor. */

export function noteWorkspaceStatus(cfg: OpenClawConfig, options: NoteWorkspaceStatusOptions = {}) {

const workspaceDir = resolveAgentWorkspaceDir(cfg, resolveDefaultAgentId(cfg));

const legacyWorkspace = detectLegacyWorkspaceDirs({ workspaceDir });

if (legacyWorkspace.legacyDirs.length > 0) {

note(formatLegacyWorkspaceWarning(legacyWorkspace), "Extra workspace");

}

const skillsReport = buildWorkspaceSkillStatus(workspaceDir, { config: cfg });

const platformIncompatibleCount = skillsReport.skills.filter(

(s) => s.platformIncompatible && !s.disabled && !s.blockedByAllowlist,

return true;

}

export type LegacyWorkspaceDetection = {

activeWorkspace: string;

legacyDirs: string[];

};

/** Detects legacy workspace directories related to the active workspace. */

export function detectLegacyWorkspaceDirs(params: {

workspaceDir: string;

}): LegacyWorkspaceDetection {

const activeWorkspace = path.resolve(params.workspaceDir);

const legacyDirs: string[] = [];

return { activeWorkspace, legacyDirs };

}

/** Formats a warning for legacy workspace directories found near the active workspace. */

export function formatLegacyWorkspaceWarning(detection: LegacyWorkspaceDetection): string {

return [

"Extra workspace directories detected (may contain old agent files):",

...detection.legacyDirs.map((dir) => `- ${shortenHomePath(dir)}`),

`Active workspace: ${shortenHomePath(detection.activeWorkspace)}`,

"If unused, archive or move to Trash.",

].join("\n");

}

export type RootMemoryFilesDetection = {

workspaceDir: string;

canonicalPath: string;

},

};

const workspaceStatusCheck: HealthCheck = {

id: "core/doctor/workspace-status",

kind: "core",

description: "Workspace directory exists and has no legacy duplicates.",

source: "doctor",

async detect(ctx) {

const { detectLegacyWorkspaceDirs } = await loadDoctorWorkspaceModule();

const workspaceDir = resolveAgentWorkspaceDir(ctx.cfg, resolveDefaultAgentId(ctx.cfg));

const legacy = detectLegacyWorkspaceDirs({ workspaceDir });

if (legacy.legacyDirs.length === 0) {

return [];

}

return [

{

checkId: "core/doctor/workspace-status",

severity: "info",

message: `Detected ${legacy.legacyDirs.length} legacy workspace director${

legacy.legacyDirs.length === 1 ? "y" : "ies"

} alongside the active workspace.`,

path: workspaceDir,

fixHint:

"Inspect the legacy directories and migrate or remove them; see `openclaw doctor` for the detailed migration prompt.",

},

];

},

};

function createSkillsReadinessCheck(deps: CoreHealthCheckDeps): HealthCheck {

return {

id: "core/doctor/skills-readiness",

gatewayConfigCheck,

...createConvertedWorkflowChecks(deps),

commandOwnerCheck,

workspaceStatusCheck,

createSkillsReadinessCheck(deps),

browserClawdProfileResidueCheck,

finalConfigValidationCheck,

createDoctorHealthContribution({

id: "doctor:workspace-status",

label: "Workspace status",

healthCheckIds: ["core/doctor/workspace-status"],

run: runWorkspaceStatusHealth,

}),

createDoctorHealthContribution({