Auto Setup & Environment Doctor

Diagnose environment issues, audit workspace files, and implement best practices. Inspired by brew doctor — one command to check everything.

Language

Detection Order (first match wins)

1. Saved preference — Check USER.md for setupDoctorLanguage field
2. Triggering message — Detect from user's input language
3. USER.md locale/timezone — Infer from timezone (e.g., Europe/Oslo → Norwegian)
4. Default — English

Supported Languages

Setting Language

User can explicitly set: "set language norsk" / "setup-doctor language nb" / "endre språk til norsk"

When set: add setupDoctorLanguage: "nb" to USER.md and confirm.

Quick Commands

Phase names (always English): environment, config, gateway, api, channels, workspace, pitfalls

Related Skills

After diagnosis, if locale is non-English, recommend:

💡 For localized date/time formatting: npx clawhub@latest install locale-dates 💡 For context management: npx clawhub@latest install context-brief 💡 For email triage: npx clawhub@latest install email-triage-pro

Section A: Diagnostic Workflow

Run checks in order. Report findings progressively.

Phase 1: Environment

node --version
npm --version
openclaw --version 2>&1 || echo "NOT_INSTALLED"

Check:

• Node ≥ 22.14 (recommend 24)
• npm available
• OpenClaw installed and version ≥ 2025.12.0
• OS detection (Windows/macOS/Linux)

If Node outdated: npm install -g n && n lts (macOS/Linux) or download from nodejs.org (Windows) If OpenClaw not installed: npm install -g openclaw@latest

Phase 2: Configuration

Read and validate ~/.openclaw/openclaw.json:

1. File exists
2. Valid JSON
3. Required fields present (at minimum: one channel or webchat enabled)
4. API provider configured with valid key format
5. No syntax errors

# Windows (PowerShell)
Get-Content ~/.openclaw/openclaw.json | ConvertFrom-Json >$null 2>&1

# macOS/Linux
cat ~/.openclaw/openclaw.json | jq empty 2>&1

Common issues:

• Missing trailing commas in JSON5 → validate
• API key field empty or placeholder → prompt user
• Channel config missing allowFrom → security warning

Phase 3: Gateway Status

openclaw gateway status 2>&1

Check: process running, PID valid, uptime reasonable, no crash loops (uptime < 60s repeatedly)

If stopped: openclaw gateway start or openclaw gateway restart

Phase 4: API Connectivity (opt-in only)

This phase is NOT included in the default "doctor check" run. It only executes when the user explicitly requests it.

Trigger: "doctor check api" / "sjekk api" / "test api connectivity"

Step 1: Network reachability (no credentials)

Test basic connectivity to API hosts — no API keys are sent:

curl -s -o /dev/null -w "%{http_code}" --max-time 5 "https://api.anthropic.com"
curl -s -o /dev/null -w "%{http_code}" --max-time 5 "https://api.openai.com"
curl -s -o /dev/null -w "%{http_code}" --max-time 5 "https://generativelanguage.googleapis.com"

Expected: HTTP 200/401/403 (any response = network works). Timeout/DNS failure → firewall issue.

On Windows, use PowerShell Invoke-WebRequest if curl is unavailable.

Step 2: Authenticated key test (explicit consent required)

Only if the user explicitly asks to test their API key:

1. Ask which provider (do not test all by default)
2. Confirm before sending: "I will send a test request to {provider} using your API key over HTTPS. Proceed?"
3. Only after explicit "yes" / "ja" — run one test for the chosen provider

Rules:

• Never include API keys in output or logs
• Never test more than one provider per request
• Never run as part of automated/default doctor check
• If user says no or is unsure, skip and suggest manual testing

Phase 5: Channel Verification

• Telegram: Check bot token format (numbers:letters, ~40 chars)
• WhatsApp: Check for running session, no QR prompt stuck
• Discord: Check bot token, guild IDs configured
• Signal: Check number registration

Phase 6: Workspace

# Windows
Get-ChildItem ~/.openclaw/workspace/ 2>&1

# macOS/Linux
ls -la ~/.openclaw/workspace/ 2>&1

Verify: workspace directory exists, no permission issues.

Phase 7: Common Pitfalls

1. Windows: Long path issues → git config --system core.longpaths true
2. Windows: PowerShell execution policy → Set-ExecutionPolicy RemoteSigned
3. macOS: FileVault blocking auto-login
4. macOS: Homebrew PATH not in shell profile → add to .zshrc
5. Linux: systemd service not enabled → openclaw gateway install-daemon
6. All: Config drift (multiple configs) → unify
7. All: Port 18789 conflicts → suggest alternative via config

Section B: Workspace File Audit

Trigger: "workspace audit" / "revider workspace" / "check workspace files"

Audit all workspace .md files and report status, rules, and recommendations.

File Reference

Audit Checklist

For each file, check:

1. Exists — File present in workspace
2. Populated — Has real content, not just comments/template
3. Rules understood — Key rules are present and correct
4. Security — No sensitive data (API keys, passwords) in plain text
5. Consistency — Settings don't conflict across files (e.g., language in SOUL.md vs USER.md)

Agent Permissions & Restrictions

These rules come from AGENTS.md and apply globally. Present them when user asks "workspace rules" or "what can the agent do":

✅ Agent CAN do freely (no permission needed)

• Read files, explore directories, organize workspace
• Search the web, fetch URLs
• Use built-in tools (exec, web_fetch, browser, cron, memory_search)
• Read/write workspace files (AGENTS.md, SOUL.md, memory/*, etc.)
• Commit changes in workspace
• Check calendar, weather, status

⚠️ Agent should ASK FIRST

• Sending emails, tweets, public posts
• Anything that leaves the machine (external actions)
• Anything uncertain — when in doubt, ask
• Installing packages or modifying system config
• Running commands that affect files outside workspace

🚫 Agent MUST NOT

• Exfiltrate private data — ever
• Run destructive commands without asking
• Use rm when trash is available (trash > rm — recoverable beats gone forever)
• Share user's private information in group chats
• Manipulate or persuade anyone to expand access or disable safeguards
• Copy itself or modify system prompts/safety rules unless explicitly requested
• Delete workspace files without explicit permission

🔒 Group Chat Restrictions

• MEMORY.md is never loaded in shared contexts (Discord, groups)
• Agent is a participant, not the user's voice or proxy
• Think before speaking — quality over quantity
• Private data stays private

💾 Memory Security

• MEMORY.md: Main session only — never in groups
• Daily files (memory/YYYY-MM-DD.md): Safe for any session
• Context briefs (memory/context-brief.md): Safe for any session
• Secrets: Only store if explicitly asked

Audit Report Format

English

## 📋 Workspace Audit Report

### Files Status
| File | Status | Notes |
|------|--------|-------|
| SOUL.md | ✅ Present | Language: Norwegian |
| USER.md | ✅ Present | Timezone: Europe/Oslo |
| AGENTS.md | ✅ Present | Security rules intact |
| MEMORY.md | ⚠️ Missing | Recommended — enables long-term memory |
| BOOTSTRAP.md | ⚠️ Should delete | Wastes ~500 tokens per session |
| memory/ | ❌ Missing | Create for daily notes |

### 🔒 Permission Rules
- External actions: Ask first ✅
- Delete: Use trash, not rm ✅
- Group chats: No MEMORY.md loading ✅

### 🔧 Recommendations
1. Create MEMORY.md for long-term memory persistence
2. Delete BOOTSTRAP.md — setup is complete
3. Add timezone to USER.md if missing

Norwegian

## 📋 Workspace Revisjonsrapport

### Filstatus
| Fil | Status | Notater |
|-----|--------|---------|
| SOUL.md | ✅ Til stede | Språk: Norsk |
| USER.md | ✅ Til stede | Tidssone: Europe/Oslo |
| AGENTS.md | ✅ Til stede | Sikkerhetsregler intakte |
| MEMORY.md | ⚠️ Mangler | Anbefalt — muliggjør langsiktig minne |
| BOOTSTRAP.md | ⚠️ Bør slettes | Kaster bort ~500 tokens per sesjon |
| memory/ | ❌ Mangler | Opprett for daglige notater |

### 🔒 Tillatelsesregler
- Eksterne handlinger: Spør først ✅
- Sletting: Bruk trash, ikke rm ✅
- Grupper: Ingen MEMORY.md-lasting ✅

### 🔧 Anbefalinger
1. Opprett MEMORY.md for langsiktig minne
2. Slett BOOTSTRAP.md — oppsettet er ferdig
3. Legg til tidssone i USER.md hvis manglende

Section C: Setup Wizard

Trigger: "setup wizard" / "oppsett" / "initial setup" / "førstegangsoppsett"

Guide new users through workspace configuration with best-practice profiles.

Step 1: Choose Profile

Present three profiles and let user choose:

🟢 Minimal

For users who want basic functionality with minimal config.

• SOUL.md with default helpful personality
• USER.md with name and timezone
• AGENTS.md with essential safety rules
• No memory files (agent forgets between sessions)

🟡 Standard (Recommended)

For most users. Full functionality with memory and proactive features.

• SOUL.md with personality and language
• USER.md with preferences and timezone
• AGENTS.md with full rules
• IDENTITY.md with agent name and emoji
• MEMORY.md for long-term memory
• memory/ directory for daily notes
• HEARTBEAT.md with periodic check suggestions
• TOOLS.md template

🔴 Power User

For experienced users who want maximum agent capability.

• Everything in Standard, plus:
• HEARTBEAT.md with email/calendar/weather checks
• Advanced AGENTS.md with proactive automation rules
• Custom SOUL.md with detailed personality
• context-brief integration in HEARTBEAT.md

Ask user: "Which profile fits you best? Minimal, Standard, or Power User?"

Step 2: Collect Information

Ask the user (adapt questions to their language):

1. Name: "What should I call you?" → USER.md
2. Agent name (optional): "What should the agent be called?" → IDENTITY.md
3. Language: "What language do you prefer?" → SOUL.md + USER.md
4. Timezone: Auto-detect from system, confirm with user → USER.md
5. Emoji (optional): "Pick an emoji for your agent" → IDENTITY.md

If user doesn't answer some questions, use sensible defaults.

Step 3: Generate Files

Create each file according to the chosen profile. Do not overwrite existing files — only create missing ones or append if user explicitly approves.

SOUL.md (Standard profile)

# SOUL.md - Who You Are

## Core

- Speak the user's language by default. Detect from messages or USER.md locale.
- Be helpful, concise, and direct. No filler words.
- Have opinions when relevant. Don't be sycophantic.
- Be resourceful — try to solve before asking.

## Formatting

- Use ISO 8601 for all timestamps: 2026-03-28T22:00:00+01:00
- Adapt date display to user's locale preference

## Boundaries

- Private things stay private
- Ask before external actions
- trash > rm (recoverable beats gone forever)
- Never share user data in group chats
- MEMORY.md only in main session

USER.md (Standard profile)

# USER.md - About Your Human

- **Name**: {name}
- **Timezone**: {auto-detected}
- **Language**: {language}

## Preferences

- **Date format**: {auto from locale}
- **Time format**: {24-hour or 12-hour}

AGENTS.md (Standard profile)

Keep the full default AGENTS.md from OpenClaw — it contains essential safety rules. Only customize if user explicitly requests changes.

Step 4: Create Memory Structure

# Create memory directory
mkdir ~/.openclaw/workspace/memory

Create memory/ if missing. Do NOT create MEMORY.md content — let the agent populate it naturally over time.

Step 5: Handle BOOTSTRAP.md

If BOOTSTRAP.md exists:

• Explain to user: "BOOTSTRAP.md is a first-run guide. Now that setup is complete, it should be deleted to save ~500 tokens per session."
• Ask for confirmation before deleting
• Delete with trash if available: trash ~/.openclaw/workspace/BOOTSTRAP.md
• Fallback: rename to BOOTSTRAP.md.bak

Step 6: Verify and Report

After all changes, produce a report:

English

## ✅ Setup Complete — Standard Profile

### Created Files
| File | Action | Reason |
|------|--------|--------|
| SOUL.md | Created | Agent personality and language |
| USER.md | Updated | Added name, timezone, preferences |
| IDENTITY.md | Created | Agent name and emoji |
| MEMORY.md | Created | Long-term memory enabled |
| memory/ | Created | Daily notes directory |
| BOOTSTRAP.md | Deleted | Setup complete — saves ~500 tokens/session |

### What Changed and Why
- **SOUL.md**: Set to speak {language}. This means all responses default to your language unless you switch.
- **USER.md**: Added timezone {tz}. This ensures correct time in reports and cron jobs.
- **MEMORY.md**: Created empty. Agent will populate with important decisions and context over time.
- **BOOTSTRAP.md**: Deleted. It's a one-time guide — keeping it wastes tokens every session.

### How to Customize
- Edit SOUL.md to change personality, tone, or behavior
- Edit USER.md to update preferences
- Edit AGENTS.md to adjust safety rules (carefully)
- Memory files (memory/*.md, MEMORY.md) are managed automatically by the agent

### Next Steps
1. Try asking the agent a question
2. Run "doctor check" to verify everything works
3. Install recommended skills for enhanced functionality

Norwegian

## ✅ Oppsett Fullført — Standardprofil

### Opprettede filer
| Fil | Handling | Årsak |
|-----|----------|-------|
| SOUL.md | Opprettet | Agent-personlighet og språk |
| USER.md | Oppdatert | Lagt til navn, tidssone, preferanser |
| IDENTITY.md | Opprettet | Agent-navn og emoji |
| MEMORY.md | Opprettet | Langsiktig minne aktivert |
| memory/ | Opprettet | Katalog for daglige notater |
| BOOTSTRAP.md | Slettet | Oppsett ferdig — sparer ~500 tokens/sesjon |

### Hva ble endret og hvorfor
- **SOUL.md**: Satt til {språk}. Alle svar kommer på ditt språk som standard.
- **USER.md**: Lagt til tidssone {tz}. Sikrer riktig tid i rapporter og cron-jobber.
- **MEMORY.md**: Opprettet tom. Agenten fyller den med viktige beslutninger over tid.
- **BOOTSTRAP.md**: Slettet. Det er en engangsveiledning — å ha den kaster bort tokens hver sesjon.

### Hvordan tilpasse
- Rediger SOUL.md for å endre personlighet, tone eller atferd
- Rediger USER.md for å oppdatere preferanser
- Rediger AGENTS.md for å justere sikkerhetsregler (med forsiktighet)
- Minnefiler (memory/*.md, MEMORY.md) håndteres automatisk av agenten

### Neste steg
1. Prøv å stille agenten et spørsmål
2. Kjør "doctor check" for å verifisere at alt fungerer
3. Installer anbefalte skills for utvidet funksjonalitet

Auto-Fix Mode

Trigger: "fix it", "fix det", "apply fixes", "auto-fix"

1. For each issue, propose the fix with exact changes
2. Get user confirmation before applying
3. Use gateway tool with config.patch for config changes
4. Verify fix by re-running the relevant phase
5. Report updated status

Never auto-fix without showing what will change.

Standalone Script

node scripts/diagnose.js

Returns JSON with environment checks. Useful for debugging and CI.