Commands/Admin/ — Administrative Commands & Management
Permission gating, diagnostics, health checks, and system administration
The Admin sub-module provides all system management capabilities for OpenClaw operators. It implements permission gating through DM policies and allowlists, runs doctor diagnostics to detect and auto-repair configuration and state integrity issues, monitors system health across config, daemon, network, and storage subsystems, and manages session lifecycle with cleanup operations.
📚 What is this & why does it exist?
The Admin sub-module is OpenClaw’s operational control center. It answers questions like “who is allowed to talk to my bot?” (permission gating), “is my system healthy?” (health checks), and “what’s broken and how do I fix it?” (doctor diagnostics). Without these tools, operators would have to manually inspect config files and state directories to troubleshoot problems.
💡 Real-world analogy
Think of Admin like the building manager’s office in a large apartment complex. The permission gating is like the intercom buzzer system — deciding who can enter and who gets turned away. The doctor diagnostics are like a building inspector who checks every apartment for problems (leaky pipes, broken locks) and can auto-fix minor issues. The health check is the daily status board showing which elevators are running, if the power is on, and whether the water pressure is normal.
Contents
Architecture
flowchart TD
subgraph Admin["Admin Command Layer"]
Doctor["Doctor Commands
doctor.ts"]
Health["Health Checks
health.ts"]
Status["Status Display
status.command.ts"]
Sessions["Session Cleanup
sessions-cleanup.ts"]
end
subgraph DoctorChecks["Doctor Subsystem"]
StateInt["State Integrity
doctor-state-integrity.ts"]
LegacyCfg["Legacy Config
doctor-legacy-config.ts"]
GwSvc["Gateway Services
doctor-gateway-services.ts"]
Allowlist["Allowlist Repair
doctor/shared/allowlist*.ts"]
end
subgraph HealthChecks["Health Subsystem"]
CfgCheck["Config Validity"]
DaemonCheck["Daemon Status"]
NetCheck["Network Connectivity"]
StorageCheck["Storage Availability"]
end
Doctor --> StateInt
Doctor --> LegacyCfg
Doctor --> GwSvc
Doctor --> Allowlist
Health --> CfgCheck
Health --> DaemonCheck
Health --> NetCheck
Health --> StorageCheck
Status --> Health
Key Classes
| Class / Function | File | Purpose |
|---|---|---|
doctorStateIntegrity() | doctor-state-integrity.ts | Validate session store JSON consistency (851 LOC) |
doctorLegacyConfig() | doctor-legacy-config.ts | Detect legacy config issues and suggest migrations (955 LOC) |
doctorGatewayServices() | doctor-gateway-services.ts | Validate Matrix, SSH, WebSocket gateway connectivity |
maybeRepairAllowlistPolicyAllowFrom() | doctor/shared/allowlist-policy-repair.ts | Restore allowFrom entries from pairing store |
maybeRepairOpenPolicyAllowFrom() | doctor/shared/open-policy-allowfrom.ts | Ensure wildcard “*” in allowFrom for open DM policy |
resolveAllowFromMode() | doctor/shared/allow-from-mode.ts | Determine allowFrom storage location per channel |
statusCommand() | status.command.ts | Comprehensive system status display (794 LOC) |
healthCheck() | health.ts | System readiness check (845 LOC) |
sessionsCleanup() | sessions-cleanup.ts | Remove stale sessions to reclaim storage |
emitDoctorNotes() | doctor/emit-notes.ts | Format and output diagnostic findings |
Data Structures
| Type | Name | Description |
|---|---|---|
| interface | DoctorCheckResult | Diagnostic finding: category, status (pass/warn/fail), message, remediation hint, details |
| interface | HealthSummary | System health: config ok, daemon running/version, network connectivity, storage available/quota |
| type | AllowFromMode | Storage location for allowFrom: “topOrNested” | “nestedOnly” | “topOnly” |
| interface | ConfigMutationState | Tracks repair changes during doctor auto-fix operations |
| interface | SessionDisplayRow | Session display: key, model, flags, age, token usage |
| enum | DoctorCategory | Categories: state-integrity, auth, config, gateway-services |
Interactions
| Direction | Partner | Interface | Description |
|---|---|---|---|
| → | config/ | loadConfig() | Read current system configuration |
| → | config/ | replaceConfigFile() | Write repaired config after doctor fixes |
| → | infra/ | providerUsage() | Fetch token/cost tracking data per provider |
| → | infra/ | heartbeat() | Check daemon process status |
| → | plugin-sdk/ | authProviderSchemas() | Validate auth configurations against provider schemas |
| ← | terminal/ | RuntimeEnv | Output log/warn/error for diagnostic reports |
Configuration
| Knob / Parameter | Default | Description |
|---|---|---|
--repair | false | Enable auto-repair for doctor findings |
--verbose | false | Show detailed diagnostic output |
--category | all | Filter doctor checks: state-integrity, auth, config, gateway-services |
--check | all | Health check scope: config, daemon, network, storage |
--older-than | 30 days | Session cleanup age threshold |
--json | false | Output JSON for programmatic consumption |
dmPolicy | “open” | DM permission policy: “open” (allow all) or “allowlist” |
allowFrom | [“*”] | Array of allowed sender IDs (or “*” wildcard) |
Directory Map
Source tree for Admin
src/commands/
├── doctor.ts ← Doctor entry point
├── doctor-state-integrity.ts ← Session store validation (851 LOC)
├── doctor-legacy-config.ts ← Legacy config migration (955 LOC)
├── doctor-gateway-services.ts ← Gateway connectivity checks
├── doctor/
│ ├── emit-notes.ts ← Diagnostic output formatting
│ ├── shared/
│ │ ├── allowlist.ts ← Permission gating core
│ │ ├── allowlist-policy-repair.ts ← Allowlist auto-repair
│ │ ├── allow-from-mode.ts ← Storage location resolver
│ │ ├── open-policy-allowfrom.ts ← Open policy wildcard repair
│ │ ├── empty-allowlist-scan.ts ← Empty allowlist detection
│ │ ├── exec-safe-bins.ts ← Safe binary execution
│ │ └── config-mutation-state.ts ← Repair tracking
│ └── providers/ ← Channel-specific doctor checks
│ ├── discord.ts
│ ├── matrix.ts
│ └── telegram.ts
├── status.command.ts ← Main status display (794 LOC)
├── status.types.ts ← Status type definitions
├── status.summary.ts ← Summary generation
├── status.format.ts ← Output formatting
├── health.ts ← System health checks (845 LOC)
├── sessions.ts ← Session listing
├── sessions-cleanup.ts ← Stale session removal
└── sessions-table.ts ← Session table formatting
Deep-Dive Highlights
Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration.
Deep-Dive Pages
Permission Gating Focus
DM policy enforcement and allowlist management. Covers the open/allowlist policy model, AllowFromMode storage strategies, and auto-repair of permission configurations across channels.
Admin Operations Focus
The config-modify-persist lifecycle used by all administrative commands. Covers snapshot loading, conflict detection, atomic writes, and backup rotation patterns.
Diagnostics Commands Focus
Doctor diagnostic pipeline: state integrity scanning, legacy config detection, gateway service validation, and the auto-repair system with remediation hints.
Code Examples
Example: Doctor Check Result
export type DoctorCheckResult = {
category: "state-integrity" | "auth" | "config" | "gateway-services";
status: "pass" | "warn" | "fail";
message: string;
remediation?: string;
details?: Record<string, unknown>;
};
Example: Health Summary Type
export type HealthSummary = {
config?: { ok: boolean; error?: string };
daemon?: { running: boolean; version?: string };
network?: { connectivity: "ok" | "limited" | "offline" };
storage?: { available: boolean; quota?: number };
};