Sections written: - Getting Started (what-is-openacp, for-users, for-developers, for-contributors) - Platform Setup (Telegram, Discord, Slack) - Using OpenACP (commands, sessions, agents, permissions, voice, files) - Self-Hosting (installation, configuration, daemon, security, logging, updating) - Features (tunnel, context-resume, usage, persistence, handoff, doctor, assistant) - Extending (plugin-system, building-adapters, adapter-reference, contributing) - API Reference (CLI commands, REST API, config schema, env vars) - Troubleshooting (Telegram, Discord, Slack, agent issues, FAQ) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.4 KiB
Doctor
What it is
openacp doctor runs a suite of system health checks and reports the status of every major component. It is the fastest way to diagnose why something is not working — misconfigured tokens, missing agent binaries, stale PID files, corrupt sessions data, and more.
Running doctor
From the terminal:
openacp doctor
From inside Telegram or Discord, send /doctor in the Assistant topic.
Each check produces one or more results with a status of pass, warn, or fail. A summary line at the end shows total counts.
Checks
| Check | What it verifies |
|---|---|
| Config | Config file exists, is valid JSON, passes schema validation, and has no pending migrations |
| Agents | Each configured agent's binary exists on PATH; flags a missing default agent as a failure |
| Telegram | Bot token is set, the bot can reach the Telegram API, and the configured chat ID resolves to a supergroup with forum topics enabled |
| Discord | Bot token and guild ID are set, the bot can connect and access the configured guild |
| Storage | ~/.openacp/ directory exists and is writable; sessions.json is valid; log directory exists and is writable |
| Workspace | The configured workspace.baseDir exists and is readable |
| Plugins | Plugins directory exists; each installed plugin can be loaded without errors |
| Daemon | PID file is valid and the process is alive; API port file is valid; API port is in use by OpenACP (not another process) |
| Tunnel | Tunnel is enabled; configured provider is recognized; cloudflared binary is present (for Cloudflare provider); tunnel port is in valid range |
Auto-fix
Some issues can be fixed automatically. When a fix is marked as safe (low risk), doctor applies it immediately and reports what was done. Examples of safe auto-fixes:
- Applying pending config migrations
- Removing a stale or invalid PID file
- Removing an invalid API port file
- Creating a missing log directory
- Installing the
cloudflaredbinary
Fixes that are risky (could cause data loss, such as resetting a corrupt sessions file) are listed as pending and require explicit confirmation before they are applied.
Exit code
openacp doctor exits with code 0 if all checks pass or produce only warnings. It exits with code 1 if any check fails. This makes it usable in CI or startup scripts:
openacp doctor || exit 1