Troubleshooting & Doctor
Relevant source files
The following files were used as context for generating this wiki page:
The Troubleshooting & Doctor system in Clawdbot is a diagnostic and repair framework designed to maintain the health and integrity of the bot's environment. Its primary purpose is to identify and resolve configuration issues, migration requirements, and service inconsistencies that may arise during updates or rebrands.
This system provides developers and users with a centralized way to audit the application state, ensuring that the gateway, agents, and messaging channels are correctly configured and reachable. It acts as a safeguard during the self-update process and serves as the first point of contact for resolving legacy service warnings or misconfigurations.
Sources: CLAUDE.md:155-156, src/commands/doctor-config-flow.ts:121-125
The Doctor Command Architecture
The doctor command is the core diagnostic tool. It operates by performing a series of checks across config files, filesystem state, and running services. It follows a structured flow of loading configuration, detecting anomalies, and offering interactive or automated repairs.
Configuration Analysis and Repair
The system analyzes the clawdbot.json configuration file to detect invalid keys, legacy settings, or missing required fields. It uses the loadAndMaybeMigrateDoctorConfig function to handle schema validation and automated migrations.
Diagnostic Checks
The Doctor performs several critical integrity checks summarized in the table below:
| Check Category | Description | Source File |
|---|---|---|
| State Integrity | Verifies the existence and accessibility of the CLAWDBOT_STATE_DIR. | doctor.warns-state-directory-is-missing.test.ts:321-325 |
| Sandbox Configuration | Detects ignored sandbox overrides (docker/browser/prune) when shared scope is active. | doctor.warns-per-agent-sandbox-docker-browser-prune.test.ts:250-260 |
| Workspace Safety | Warns about extra workspace directories that might cause confusion. | doctor.warns-per-agent-sandbox-docker-browser-prune.test.ts:285-295 |
| OpenCode Zen | Identifies provider overrides that mask built-in routing or costs. | src/commands/doctor-config-flow.ts:91-105 |
| Gateway Auth | Checks if Gateway authentication tokens are missing or insecurely configured. | doctor.warns-state-directory-is-missing.test.ts:371-380 |
Troubleshooting through Status Audits
While the Doctor command repairs, the status command provides the necessary visibility for manual troubleshooting. It aggregates data from various subsystems to present a real-time health snapshot.
Status Components
The status output is divided into logical blocks, each focusing on a specific subsystem:
- Overview: Displays OS info, Node version, Tailscale status, and active Gateway mode.
- Security Audit: Runs an automated scan for critical vulnerabilities, including filesystem and channel security issues.
- Channel Health: Monitors the state of messaging channels (Signal, Discord, etc.), flagging unlinked or misconfigured providers.
- Memory & Storage: Shows the status of Full-Text Search (FTS), vector stores, and memory cache.
- Service Daemons: Reports whether the Gateway and Node services are correctly installed and loaded.
Data Flow for Status Reporting
The following diagram illustrates how the status command aggregates data from disparate sources:
Self-Update Troubleshooting
The update system includes built-in guards to prevent system corruption during version changes. If an update fails, the system provides specific logs and exit codes to aid recovery.
Update Safety Guards
- Dirty Directory Check: The update will skip if the working directory has uncommitted changes to prevent data loss.
- Downgrade Confirmation: Users must explicitly confirm downgrades (e.g., switching from
betatostable) as they can break configurations. - Doctor Integration: After an update and service restart, the system automatically triggers a
doctorcheck to ensure the new version is compatible with the existing environment.
Sources: src/cli/update-cli.ts:420-435, src/cli/update-cli.ts:512-515, src/cli/update-cli.ts:604-610
Global Install Troubleshooting
For global installations, the system attempts to detect the package manager used (npm, pnpm, or bun) to ensure updates are applied through the correct toolchain.
Common Troubleshooting Steps
| Symptom | Tool/Command | Remediation |
|---|---|---|
| Unreachable Gateway | clawdbot gateway probe | Verify Gateway service status; check if port 18789 is bound. |
| Invalid Config Keys | clawdbot doctor --fix | Runs automated stripping of unknown keys and legacy migrations. |
| Failed Post-Update | clawdbot logs --follow | Check for startup errors; use doctor to repair environment state. |
| Channel WARN state | clawdbot status --deep | Triggers a live probe of messaging provider connectivity. |
| Security Findings | clawdbot security audit | Follow the "Fix" hints provided in the audit results. |
| Sources: src/commands/status.command.ts:503-509, src/commands/doctor-config-flow.ts:200-205, src/commands/status.command.ts:365-375 |
Conclusion
The Troubleshooting & Doctor system provides a robust, multi-layered approach to maintaining Clawdbot. By combining proactive schema migration in the doctor command with deep-probe diagnostics in the status command, the project ensures that both core gateway functions and extension channels remain operational through updates and configuration changes. The integration of automated security audits and health checks makes it a comprehensive toolset for system administrators and developers alike.