DoctorClaw: AI System Diagnostics with Ollama

What Is DoctorClaw? The AI-Powered System Diagnostics Assistant

DoctorClaw is a lightweight, privacy-first system troubleshooting agent that brings the power of local large language models to everyday system administration and diagnostics. Built on top of Ollama, DoctorClaw transforms how developers and system administrators interact with their machines by enabling natural language troubleshooting conversations that can diagnose issues, execute commands, read configuration files, and even apply fixes — all while maintaining strict approval-based controls to ensure system safety.

What sets DoctorClaw apart from traditional system administration tools is its interactive, conversational approach. Instead of memorizing complex command sequences or scrolling through documentation, users can simply describe their problem in plain English: "My disk is full, help me find what's taking up space" or "Why won't my Docker containers start?" The AI agent then walks through diagnostic steps, proposing specific actions that users approve or deny before execution.

Architecture and Technical Approach

Core Technology Stack

DoctorClaw's architecture is deliberately minimalist, prioritizing ease of deployment and transparency over complexity. The entire system consists of a Node.js Express server (server.mjs) that acts as both the application backend and Ollama API proxy, paired with a single-file HTML frontend that provides the chat interface, settings management, and session handling.

This lightweight approach offers several advantages. The minimal dependencies reduce the attack surface and make the codebase easy to audit. The single-file frontend means no complex build processes or bundlers — just open the HTML in a browser and start troubleshooting. The Node.js backend provides cross-platform compatibility across Linux, macOS, and Windows without platform-specific compilation.

The Four-Action Security Model

At the heart of DoctorClaw's design is a strict action model that defines exactly what the AI can request. Every interaction with the system falls into one of four categories:

• Read File: Access file contents from approved readable directories
• Run Command: Execute shell commands after blocklist validation
• Run Script: Execute shell, batch, or PowerShell scripts from readable paths
• Write File: Create or modify files in approved writable directories with automatic backup

Each action appears as an interactive card in the chat interface with clear "Approve" and "Deny" buttons. The AI model receives the result only after user approval, creating a human-in-the-loop workflow that prevents autonomous system modifications. If an action is denied, DoctorClaw adapts its troubleshooting approach and suggests alternatives.

Multi-Layered Safety Architecture

DoctorClaw implements defense-in-depth security through multiple complementary layers. Path restrictions confine file operations to explicitly configured directories — attempts to access /etc/passwd or system files outside approved paths are automatically rejected. The command blocklist proactively filters dangerous patterns including rm -rf, mkfs, dd, shutdown commands, fork bombs, and pipes to shell interpreters before they reach the approval stage.

All file modifications trigger automatic backups to .doctorclaw-backups/ with timestamps, enabling easy rollback if changes cause issues. Commands and scripts run with timeout limits (30 seconds for commands, 60 seconds for scripts) to prevent resource exhaustion. Scripts execute with their containing directory as the working directory, limiting unintended side effects.

Ollama Integration and Local LLM Processing

DoctorClaw's reliance on Ollama for local LLM inference is a critical architectural decision. Unlike cloud-based AI troubleshooting tools, all processing happens on your hardware with your chosen model. This ensures diagnostic conversations about sensitive system configurations, log files, and error messages never leave your network. The default model, glm-4.7:cloud, provides a good balance of capability and resource requirements, but users can swap in any Ollama-compatible model.

The server acts as a proxy to the Ollama API, translating chat messages into streaming completions while injecting system prompts that teach the model about available actions and safety constraints. This approach keeps the frontend simple while enabling sophisticated prompt engineering and context management on the backend.

Getting Started with DoctorClaw

One-Command Installation

DoctorClaw provides thoughtfully designed installers that handle the entire setup process, making it accessible even to users unfamiliar with Node.js development. The installation scripts detect your operating system, verify Node.js version 18 or higher (offering to install it if missing), pull project dependencies, generate a default configuration file tailored to your OS, check for Ollama availability, and start the server.

On macOS or Linux systems, installation is as simple as:

chmod +x install.sh
./install.sh

Windows users can simply double-click install.bat to launch the automated setup process. These installers represent a commitment to accessibility — powerful system diagnostic tools shouldn't require extensive setup expertise.

Manual Setup for Advanced Users

Users with existing Node.js and Ollama installations can bypass the installer and set up DoctorClaw manually in three steps. First, pull an appropriate model from Ollama's library (the default is ollama pull glm-4.7:cloud). Second, install project dependencies with npm install. Finally, start the server with npm start and navigate to http://localhost:3333 in your browser.

This manual approach gives experienced users full control over the installation process and makes it easy to integrate DoctorClaw into existing development workflows or containerized environments.

Interactive First-Run Configuration

The first time DoctorClaw starts without an existing configuration file, it launches an interactive setup wizard in the terminal. This wizard walks through essential configuration choices: which Ollama model to use (with auto-detection of locally available models), the Ollama API URL, the OpenClaw installation directory if applicable, your operating system, and which directories should be readable or writable.

Two command-line flags provide flexibility for different scenarios. The -i or --interactive flag forces the setup wizard to run even if a configuration exists, useful for reconfiguring settings. The -y or --yes flag skips all prompts and uses defaults or existing configuration, perfect for automated deployments or CI/CD pipelines.

Key Features and Capabilities

Natural Language System Diagnostics

The core value proposition of DoctorClaw is transforming system troubleshooting from a command-line exercise into a conversation. Users describe issues in plain English without needing to know the exact commands or log file locations. "My website isn't loading" becomes a guided diagnostic session where DoctorClaw proposes checking network connectivity, examining web server logs, verifying service status, and testing port availability — all through approved actions.

This conversational approach is particularly valuable for complex multi-step troubleshooting where the next diagnostic step depends on previous results. DoctorClaw maintains context throughout the session, remembering what's been checked and what was discovered, enabling coherent diagnostic flows.

Approval-Gated Action System

Every system interaction — whether reading a configuration file, running df -h to check disk space, executing a cleanup script, or modifying a settings file — appears as an action card in the chat interface. These cards clearly display what will happen, what parameters are involved, and provide prominent Approve and Deny buttons. This transparency ensures users understand exactly what the AI wants to do before it happens.

The approval gate serves multiple purposes beyond security. It creates educational opportunities where users learn which commands and files are relevant to their issue. It builds trust by making AI decision-making visible rather than opaque. It enables users to intervene if the AI's troubleshooting approach seems suboptimal.

Multi-Session Tab Interface

DoctorClaw supports running multiple troubleshooting sessions simultaneously through a tab-based interface. Each tab maintains its own conversation history, context, and pending actions. This is invaluable when diagnosing multiple unrelated issues or when you want to preserve a successful diagnostic session for future reference while exploring a new problem.

Session state persists in browser local storage, meaning your troubleshooting history survives page refreshes and even browser restarts. You can return to a diagnostic conversation hours later and pick up exactly where you left off.

Script Execution Support

Beyond individual commands, DoctorClaw can execute full scripts including .sh, .bash, .bat, .cmd, and .ps1 files located in readable directories. This enables sophisticated diagnostic and repair workflows that might involve multiple commands, conditional logic, or complex text processing.

Scripts run in a sandboxed context with their containing directory as the working directory and a 60-second timeout. This prevents runaway scripts while still enabling powerful automation. The approval system shows the script path and location before execution, allowing users to review the script content before approving.

Automatic Backup and Rollback

Any time DoctorClaw modifies a file, it first creates a timestamped backup in .doctorclaw-backups/. This automatic backup system provides a safety net for configuration changes and enables easy rollback if a modification causes unexpected issues. The backup directory structure mirrors the original file paths, making it easy to locate the backup of any modified file.

This feature is particularly valuable when experimenting with configuration changes or allowing the AI to apply fixes. If something goes wrong, you have a clear audit trail and restoration path.

Settings UI and Configuration Management

All DoctorClaw settings are accessible through a web-based settings panel (accessed via the gear icon in the interface header). Users can modify the server port, Ollama API URL, model selection, readable and writable paths, and operating system without editing JSON configuration files directly. Changes to paths take effect immediately, while changes to port, model, or Ollama URL require a server restart.

This UI-driven configuration approach makes DoctorClaw accessible to users who are uncomfortable editing configuration files and reduces the risk of syntax errors breaking the configuration.

OS-Aware Command Generation

DoctorClaw adapts its command syntax and diagnostic approach based on the configured operating system. Linux, macOS, and Windows each have different tools, command syntaxes, and file path conventions. DoctorClaw's OS awareness ensures suggested commands and scripts are appropriate for your platform, avoiding the frustration of Linux commands being suggested on Windows systems.

Experimental Audio Conversational Interface

For users seeking a hands-free troubleshooting experience, DoctorClaw includes experimental support for voice-based interaction. Through integration with speech-to-text services and ElevenLabs text-to-speech, users can speak their diagnostic questions and hear responses spoken aloud. This audio interface is documented in EXPERIMENTAL-FEATS.md and requires additional API configuration.

While still experimental, this feature points toward a future where system troubleshooting can happen entirely through voice commands — particularly useful when working in server rooms or situations where typing is impractical.

Community and Ecosystem Context

The OpenClaw Relationship

DoctorClaw's tagline — "When OpenClaw goes wrong, or your computer is just feeling blue" — hints at a relationship with the OpenClaw project. While DoctorClaw is designed as a general-purpose system diagnostics tool, it includes specific configuration options for OpenClaw installation directories, suggesting it may have originally been developed as a troubleshooting companion for OpenClaw deployments.

This origin story highlights an important use case: complex open-source projects often develop their own ecosystem of helper tools. DoctorClaw demonstrates how AI-powered diagnostics can be packaged as standalone utilities to help users troubleshoot and maintain software installations.

The Local-First AI Movement

DoctorClaw is part of a broader movement toward local-first AI tooling. By building on Ollama rather than cloud APIs, it joins projects advocating for AI that runs on user hardware, preserving privacy and enabling offline operation. This approach is particularly important for system administration tools that necessarily interact with sensitive configuration data, credentials, and system internals.

ollama The choice of Ollama as the LLM runtime connects DoctorClaw to a thriving ecosystem of local model runners and model communities experimenting with on-device AI.

Contributing to DoctorClaw

The project maintains an MIT license and actively seeks contributors. The README's "Calling All Hands" section explicitly invites developers interested in AI, frontend development, backend engineering, and DevOps to help shape the project's future. With minimal stars and forks on GitHub, DoctorClaw is an early-stage project where contributors can have meaningful impact on the architecture and direction.

The simple, transparent codebase — a single server file and single frontend file — makes DoctorClaw an excellent project for developers learning about AI agent architectures, human-in-the-loop systems, or Ollama integration.

Future Development and Roadmap

Safety and Security Enhancements

While DoctorClaw implements multiple security layers, there are opportunities for additional safety mechanisms. Potential enhancements include more sophisticated command analysis using abstract syntax trees rather than simple pattern matching, integration with system audit logs to track all DoctorClaw actions, user-defined command allowlists for high-security environments, and role-based access controls for multi-user scenarios.

The approval-gated model could also be extended with a "dry-run" mode that shows exactly what would happen without executing, similar to --dry-run flags in many command-line tools.

Enhanced Diagnostic Capabilities

Future versions could expand DoctorClaw's diagnostic toolkit with native support for reading and parsing common log formats (systemd journals, syslog, application logs), integration with system monitoring APIs to access metrics and performance data, visual representation of system state and resource usage, and pre-built diagnostic playbooks for common issues (high CPU, disk full, network connectivity).

Integration with package managers (apt, yum, brew, chocolatey) could enable DoctorClaw to diagnose and fix software installation issues, not just system configuration problems.

Model Fine-Tuning and Specialization

While DoctorClaw works with general-purpose LLMs, there's potential for training or fine-tuning models specifically for system diagnostics. A specialized model could better understand system administration terminology, common troubleshooting patterns, and the semantics of various command outputs. The structured action system provides training data opportunities — successful diagnostic sessions could be captured and used to improve model performance.

Collaborative Diagnostics

An intriguing future direction is multi-user diagnostic sessions where multiple administrators can collaborate on troubleshooting complex issues. This could involve shared session state, approval voting for potentially dangerous actions, and real-time collaboration features similar to collaborative document editing.

Cross-Platform Agent Deployment

While DoctorClaw currently requires a browser interface, future versions could include terminal-based interfaces for SSH sessions, desktop applications for better system integration, mobile clients for on-call troubleshooting, and Slack/Discord bots for team-based diagnostics.

Practical Use Cases

Development Environment Troubleshooting

Developers frequently encounter environment-specific issues: Docker containers won't start, npm install fails with cryptic errors, database connections refuse to establish. DoctorClaw excels at walking through these scenarios, checking environment variables, examining configuration files, verifying service status, and suggesting fixes — all without leaving the context of the problem description.

Server Maintenance and Operations

System administrators managing servers can use DoctorClaw for routine diagnostics: investigating disk space warnings, analyzing log patterns, diagnosing performance degradation, and verifying service health. The approval system ensures even AI-suggested maintenance actions go through proper review before execution.

Learning and Education

For users learning system administration, DoctorClaw serves as an interactive tutor. Instead of searching documentation to find the right command, learners can describe what they want to accomplish and see DoctorClaw propose appropriate commands. The approval system creates a moment to understand what each command does before executing it.

Documentation and Audit Trails

Because DoctorClaw maintains session history showing the entire diagnostic process — questions asked, actions taken, results observed — it automatically generates documentation of troubleshooting sessions. This history can be invaluable for post-mortems, knowledge sharing, or simply remembering how a particular issue was resolved.

Technical Considerations and Limitations

LLM Capability Requirements

DoctorClaw's effectiveness depends heavily on the capabilities of the underlying language model. Smaller or less capable models may struggle to maintain diagnostic context, propose appropriate actions, or interpret complex error messages. The default glm-4.7:cloud model represents a baseline, but users with more powerful hardware may benefit from larger models.

Resource Requirements

Running local LLMs requires significant computational resources. Systems with limited RAM or older CPUs may experience slow response times or be unable to run capable models. This local-first approach trades cloud dependency for hardware requirements — a tradeoff aligned with privacy and control priorities but potentially limiting for resource-constrained environments.

Command Blocklist Limitations

While DoctorClaw's command blocklist catches common dangerous patterns, it's not foolproof. Sophisticated users could potentially craft commands that bypass pattern matching while still causing harm. The approval system remains the critical security layer — users must understand and evaluate proposed actions, not blindly approve them.

Cross-Platform Complexity

Supporting Linux, macOS, and Windows simultaneously introduces complexity in command generation and path handling. While DoctorClaw's OS awareness helps, there are inevitably edge cases where platform differences cause issues. Users must ensure their OS is correctly configured in settings for optimal results.

Information based on the DoctorClaw GitHub repository, accessed February 2026.