Admin Operations

Contents

Overview

Core Types

Admin operations revolve around four key type families: the config mutation generics, the reset scope enum, the uninstall scope set, and the agent config parameters.

// src/commands/config-io.ts — config mutation signature
export async function mutateConfigFile<T = void>(params: {
  base?: ConfigMutationBase;
  baseHash?: string;
  writeOptions?: ConfigWriteOptions;
  mutate: (
    draft: OpenClawConfig,
    context: { snapshot: ConfigFileSnapshot; previousHash: string | null }
  ) => Promise<T | void> | T | void;
}): Promise<ConfigReplaceResult & { result: T | undefined }>

// src/commands/reset.ts — reset scope types
export type ResetScope = "config" | "config+creds+sessions" | "full";

export type ResetOptions = {
  scope?: ResetScope;
  yes?: boolean;
  nonInteractive?: boolean;
  dryRun?: boolean;
};

Decision Points

How It Works

Admin operations follow three distinct patterns depending on the command: transactional config mutation for configure and agent config, scoped reset for the reset command, and multi-scope uninstall for teardown. All three patterns share the same dry-run and confirmation guardrails.

Config Mutation Lifecycle

The mutateConfigFile function implements an optimistic-concurrency protocol. It reads the current config file into a snapshot, passes a mutable draft to the caller’s mutate callback, and then performs a compare-and-swap write using the snapshot’s hash. If another process modified the file between read and write, the operation fails with a hash-conflict error rather than silently overwriting.

flowchart TD
  START["mutateConfigFile() called"]
  READ["Read config file from disk"]
  SNAP["Create ConfigFileSnapshot + hash"]
  DRAFT["Clone snapshot into mutable draft"]
  MUTATE["Execute caller's mutate(draft, context)"]
  COMPARE{"baseHash === currentHash?"}
  WRITE["Atomically write draft to disk"]
  RESULT["Return ConfigReplaceResult + result T"]
  CONFLICT["Throw hash-conflict error"]
  DRYRUN{"dryRun enabled?"}
  PREVIEW["Return preview without writing"]

  START --> READ
  READ --> SNAP
  SNAP --> DRAFT
  DRAFT --> MUTATE
  MUTATE --> DRYRUN
  DRYRUN -->|Yes| PREVIEW
  DRYRUN -->|No| COMPARE
  COMPARE -->|Match| WRITE
  COMPARE -->|Mismatch| CONFLICT
  WRITE --> RESULT

The flowchart above shows the full config mutation pipeline. The critical path runs from top to bottom: read → snapshot → draft → mutate → compare → write. The dry-run branch exits early after mutation without touching disk, and the hash-conflict branch raises an error that the caller can retry.

Configure Command

The configureCommand and configureCommandWithSections functions launch an interactive wizard that collects user input, then calls mutateConfigFile internally to persist changes. The sections parameter allows callers to restrict the wizard to specific config areas (e.g., only model settings).

// src/commands/configure.commands.ts — configure entry points
export async function configureCommand(
  runtime: RuntimeEnv = defaultRuntime
) {
  await runConfigureWizard({ command: "configure" }, runtime);
}

export async function configureCommandWithSections(
  sections: WizardSection[],
  runtime: RuntimeEnv = defaultRuntime
) {
  await runConfigureWizard(
    { command: "configure", sections },
    runtime
  );
}

Scoped Reset Flow

The resetCommand applies a progressively wider teardown depending on the chosen ResetScope. The "config" scope only removes the config file. The "config+creds+sessions" scope additionally clears stored credentials and active session tokens. The "full" scope performs a factory reset that also removes workspace artifacts, agent directories, and cached data.

sequenceDiagram
    participant User
    participant CLI as resetCommand()
    participant Confirm as Confirmation Prompt
    participant Config as Config File
    participant Creds as Credentials Store
    participant Sessions as Session Store
    participant Workspace as Workspace Artifacts

    User->>CLI: reset --scope config+creds+sessions
    CLI->>Confirm: "This will delete config, credentials, and sessions. Continue?"
    Confirm-->>CLI: yes
    CLI->>Config: Delete config file
    Config-->>CLI: OK
    CLI->>Creds: Clear stored credentials
    Creds-->>CLI: OK
    CLI->>Sessions: Invalidate active sessions
    Sessions-->>CLI: OK
    CLI-->>User: Reset complete (config + creds + sessions)

The sequence diagram shows the reset flow for the "config+creds+sessions" scope. Each store is cleared in order: config first, then credentials, then sessions. If --yes is passed, the confirmation prompt is skipped. If --dry-run is set, the command prints what it would delete without actually deleting anything.

// src/commands/reset.ts — reset command signature
export type ResetScope = "config" | "config+creds+sessions" | "full";

export type ResetOptions = {
  scope?: ResetScope;
  yes?: boolean;
  nonInteractive?: boolean;
  dryRun?: boolean;
};

export async function resetCommand(
  runtime: RuntimeEnv,
  opts: ResetOptions
)

Multi-Scope Uninstall

The uninstall command uses a scope-set pattern rather than a single enum. The buildScopeSelection helper reads individual boolean flags (--service, --state, --workspace, --app) and the --all shorthand to produce a Set<UninstallScope>. Each scope triggers a specific teardown action, and scopes execute in dependency order: service is stopped before state is removed, and workspace is cleaned before app binaries are deleted.

// src/commands/uninstall.ts — scope selection and teardown
type UninstallScope = "service" | "state" | "workspace" | "app";

export type UninstallOptions = {
  service?: boolean;
  state?: boolean;
  workspace?: boolean;
  app?: boolean;
  all?: boolean;
  yes?: boolean;
  nonInteractive?: boolean;
  dryRun?: boolean;
};

function buildScopeSelection(
  opts: UninstallOptions
): { scopes: Set<UninstallScope>; hadExplicit: boolean; }

async function stopAndUninstallService(
  runtime: RuntimeEnv
): Promise<boolean>

Code Walkthrough — applyAgentConfig

This walkthrough traces how agent configuration parameters are merged into the global OpenClawConfig object. The function uses a selective-merge strategy: only fields that are explicitly provided in the params object are overwritten; omitted fields preserve their existing values.

// src/commands/agents.config.ts — entry point
export function applyAgentConfig(
  cfg: OpenClawConfig,
  params: {
    agentId: string;
    name?: string;
    workspace?: string;
    agentDir?: string;
    model?: string;
  }
): OpenClawConfig

Setup Command

The setupCommand orchestrates first-run initialization. It creates workspace directories, writes a default config file (via mutateConfigFile), and optionally launches the configure wizard. It is safe to call on an already-initialized workspace — existing files are not overwritten.

// src/commands/setup.ts — setup entry point
export async function setupCommand(
  opts?: { workspace?: string },
  runtime: RuntimeEnv = defaultRuntime
)

Edge Cases

Configuration

Related Topics

Source Files

src/
└── commands/
    ├── config-io.ts              ← mutateConfigFile() transactional mutation
    ├── configure.commands.ts     ← configureCommand(), wizard launcher
    ├── reset.ts                  ← resetCommand(), ResetScope, ResetOptions
    ├── uninstall.ts              ← uninstallCommand(), buildScopeSelection()
    ├── agents.config.ts          ← applyAgentConfig() agent config merge
    └── setup.ts                  ← setupCommand() first-run initialization